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Topic I DEBUGGING PROGRAMS ON MULTICS Topic I 

OBJECTIVES: 

Upon completion of this topicr students should be able to: 

1. Describe the methods used to find and correct syntactical 
errors. 

2. Describe the methods used to find and correct semantic 
errors- 

3. List some of the more common source-level debussins tools. 

4. Outline? in seneral termsr the concepts of source-level 
debussins as opposed to obJect-level debussins. 
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TYPES OF PROGRAMMING ERRORS 

a TWO KINDS OF ERRORS (BUGS) COMMONLY OCCUR IN PROGRAMS 

I SYNTAX ERRORS 

I TYPING ERRORS 

I MISUSE OF A LANGUAGE STATEMENT 

' I SEMANTIC ERRORS 

I SPECIFYING THE "wrong DATA 

I USING DATA INCORRECTLY 

I ATTEMPTING TO REFERENCE MORS DATA THAN IS PRESENT 
I PERFORMING INVALID OPERATIONS ON THE DATA 

I PERFORMING AN INCORRECT SEQUENCE OF OPERATIONS ON THE DATA 
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TYPES OF PROGRAMMING ERRORS 

a SYNTAX ERRORS 

I CAN BE DETECTED BY 

T PROOFREADING THE PROGRAM 

I COMPILING THE PROGRAM AND OBSERVING THE ERROR DIAGNOSTIC 
MESSAGES 

I CAN BE CORRECTED BY 

I EDITING THE SOURCE PROGRAM TO CORRECT THE ERRORS (DIAGNOSED 
BY THE COMPILER OR FOUND DURING PROOFREADING) 

I RECOMPILING THE SOURCE 

I REPEATING THIS PROCESS UNTIL NO MORE ERRORS ARE DIAGNOSED 
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TYPES OF PROGRAMMING ERRORS 

SEMANTIC ERRORS 

I CAN BE DETECTED BY 

I PROOFREADING THE PROGRAM 

I INSERTING TEMPORARY STATEMENTS IN THE PROGRAM SOURCE TO PRINT 
INFORMATION ABOUT DATA VALUES, FLOW OF CONTROL, ETC. 

I ARE INTERMEDIATE DATA VALUES CORRECT? 

I DOES THE POINT OF EXECUTION FLOW THROUGH THE PROGRAM IN 
THE EXPECTED WAY? 

I RUNNING THE PROGRAM AND OBSERVING 

I WHETHER OR NOT THE PROGRAM RUNS TO COMPLETION 
I DOES THE PROGRAM GO INTO A LOOP? 

I DOES AN UNEXPECTED ERROR CONDITION OCCUR WHICH HALTS 
PROGRAM. EXECUTION? 

I WHETHER OR NOT THE PROGRAM PRODUCES THE EXPECTED RESULTS 

I DOES THE PROGRAM PRODUCE CORRECT OUTPUT DATA? 

I DOES THE PROGRAM DIAGNOSE INCORRECT INPUT DATA? 

I CAN BE CORRECTED BY 

I IDENTIFYING THE POINT OF ERROR 

I EDITING THE SOURCE PROGRAM TO CORRECT THE ERRORS 
I RECOMPILING THE SOURCE 
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TYPES OF PROGRAMMING ERRORS 



I REPEATING THIS PROCESS UNTIL THE PROGRAM OPERATES CORRECTLY 
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LIST OF DEBUGGING TOOLS 



B MAJOR TOOLS FOR DIAGNOSING 



I SYNTAX ERRORS 

I THE COMPILERS 

I pll 
I cobol 
I fortran 



I SEMANTIC ERRORS 

I SOURCE-LEVEL DEBUGGING TOOLS 
I probe 

I trace recv-tii^<^-e <^ s. 

I display_pll^io_error ^'^^ 

I OBJECT-LEVEL DEBUGGING TOOLS 
debug 

trace_stack 
dump_segment 
pr int_l ink__inf o 
pr int_bind_map 
display__component_narae 
pr int_l inkage_usage 
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OTHER PROGRAMMING AND DEBUGGING TOOLS 



I FILE MANIPULATION TOOLS 

I io^call 

I pr int__attach_table 

I close^file 

I vf ile__status 

I vfile^adjust 

I ad just_bit_count 

I set_bit_count 

I EXTERNAL REFERENCE MANIPULATION TOOLS 

I resolve_linkage_error 

I 1 ist__external__var iables 

I delete__external__var iables 

I reset__external_var tables 

I set_fortran_common 

I create_data__seginent 

I er ror_table_coinpiler 

I COBOL RUN UNIT TOOLS 

I run_cobol 

I display_cobol_run_uni t 

I stop_cobol_run 

I cancel cobol^prog ram 
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OTHER PROGRAMMING AND DEBUGGING TOOLS 



I GENERAL RUN UNIT COMMANDS 

I run 

I stop__run 

I SEARCH RULE AND DYNAMIC LINKING TOOLS 

I pr int_search__ruies 

I add__search_rules 

I delete_search__rules 

I where 

I 1 ist_ref_names 

I initiate 

I terminate 

I terminate__ref name 

I terminate_single_ref name 

I terminate_segno l^^* fcAOwfe/ae ef^ 



I AREA MANIPULATION TOOLS 
I area_status 
I create^area 
I set__user__storage 
I set__system_storage 
I list_temp_segments 
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SOURCE-LSVSL DEBUGGING 

B SOURCE-LEVEL DEBUGGING ALLOWS THE PROGRAMMER TO 

I DISPLAY PROGRAM SOURCE STATEMENTS 
I GIVEN A STATEMENT LABEL 
I GIVEN A LINE NUMBER 

I DISPLAY THE VALUE OF PROGRAM DATA VARIABLES 
I GIVEN THE NAME OF THE VARIABLE 

I DISPLAY THE VALUE OF PROGRAM DATA VARIABLES 

I GIVEN THE STORAGE LOCATION AND DATA FORMAT OF THE VARIABLE 

I DISPLAY THE DECLARATION OF A PROGRAM VARIABLE 

I DISPLAY THE LIST OF (USER RING) ACTIVE PROGRAMS 
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SOURCE-LEVEL DEBUGGING 



H SOURCE-LEVEL DEBUGGING ALLOWS THE PROGRAMMER TO 

I SET BREAKPOINTS BEFORE OR AFTER STATEMENTS 
I TO INTERRUPT NORMAL FLOW OF EXECUTION 
I TO INTERROGATE THE STATE OF THE EXECUTING PROGRAM 
I TO CHANGE THE VALUE OF PROGRAM DATA 

I TO ALTER THE FLOW OF EXECUTION THROUGH THE PROGRAM 

I TO CONDITIONALLY PERFORM ANY OF THESE FUNCTIONS 

I ONLY IF A PROGRAM DATA VALUE MEETS SOME CONDITION 

I REPEATEDLY WHILE A PROGRAM DATA VALUE MEETS SOME CONDITION 

I TRACE CALLS TO A PARTICULAR PROGRAM 

I CALL PROGRAMS WHICH EXPECT NON-CHARACTER ARGUMENTS 
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OBJECT LEVEL DEBUGGING 



a OBJECT-LEVEL DEBUGGING TOOLS ALLOW THE PROGRAMMER TO 

I PERFORM MOST SOURCE-LEVEL DEBUGGING FUNCTIONS, PLUS 

I CHANGE THE VALUE OF PROGRAM DATA VARIABLES 

I GIVEN THE STORAGE LOCATION AND DATA FORMAT OF THE VARIABLE 

I DISPLAY PROGRAM SOURCE STATEMENTS 

I GIVEN A LOCATION IN THE PROGRAM OBJECT SEGMENT 

r DISPLAY AND CHANGE THE VALUE OF MACHINE INSTRUCTIONS COMPILED TO 
EXECUTE A SOURCE STATEMENT 

I DISPLAY THE FORMATTED CONTENTS OF 

I THE PROGRAM ACTIVATION HISTORY SEGMENT (THE STACK) 
I AREA SEGMENTS 
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OBJECT LEVEL DEBUGGING 

a OBJECT-LEVEL DEBUGGIHG TOOLS ALLOW THE PROGRAMMER TO 

I DISPLAY AND CHANGE THE CONTENTS OF ANY SEGMENT 
I GIVEN ITS PATHNAME 
I GIVEN ITS REFERENCE NAME 
I GIVEN ITS SEGMENT NUMBER 

I WHEN THE USER HAS ADEQUATE ACCESS TO PERFORM THE REQUESTED 
OPERATION 

I DISPLAY AND CHANGE THE CONTENTS OF HARDWARE REGISTER IMAGES 
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Topic II SOURCE-LEVEL DEBUGGING (PROBE) Topic II 

OBJECTIVES: 

Upon completion of this topicr students should be able to: 

1. Use the appropriate PL/1 compiler control arsuments to enable 
probe to function on an object sesment. 

2- Describe the different situations under which probe may be 
i nvoked . 

3. Debus a program usins the following probe re<iuests: 

source (sc) 
value (v) 
symbol (sb) 
*iuit in ) 
help 

stack (sk) 

4. ^fanipulate breakpoints in a program usins the following probe 
re*?uestss 

position Cps)r status (st) 

be fore (b>» after (a)» reset <r) 

continue ic)f continue_to (ct)» step <s) 

5. Use the probe builtin functions. 
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THE PROBE ENVIRONMENT 



I FUNCTIONS AS A SUBSYSTEM FOR PROGRAM RECOVERY 

I DRIVEN BY INTERACTIVE REQUESTS 

I LONG AND SHORT FORMS AVAILABLE 

I REQUEST DELIMITER IS EITHER NEW LINE OR SEMI-COLON 

I WORKS BEST WITH COMPILER GENERATED SYMBOL TABLE 

I CURRENTLY AVAILABLE FOR COBOL, FORTRAN, AND PL/I 

I USE -table OPTION 

I MAY ALSO USE -short table OPTION 



r 07:47 0.159 43 

pll check^back^issues -sv2 
PL/I 26a 

r 07:48 3.391 221 
probe check^back^issues 

probe: Cannot get statement map for this procedure, 
r 07:48 0.108 31 

pll check back^issues -sv2 -tb 

PL/I 26a " 

r 07:48 3.486 217 

probe check^back_issues 

Using check~back_issues (no active f rame) , f»o^ \^cu-. 
source " 
check_back__issues : 
proc; 

qui t 

r 07:49 0.173 21 
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THE PROBE ENVIRONMENT 



I MAY BE INVOKED FROM SEVERAL SITUATIONS 

I AFTER AN UNHANDLED CONDITION (READY LEVEL NOT EQUAL TO ONE) 
I AT READY LEVEL ONE WITH NO PROGRAM SPECIFIED ] 0 ?<^-^>-c 
I AT READY LEVEL ONE WITH PROGRAM SPECIFIED 
I IMPLICITLY AT A PREVIOUSLY SET BREAKPOINT 

I MANAGES TWO IMPORTANT PIECES OF INFORMATION 

I SOURCE POINTER 

I FRAME OF PROGRAM (ONLY IF ACTIVE) 

I BLOCK OF CODE WITHIN PROGRAM 

I LINE OF CODE WITHIN PROGRAM 

I BASED UPON MANNER OF INVOCATION 

I CONTROL POINTER 

I LAST INSTRUCTION EXECUTED 

I BASED UPON MANNER OF INVOCATION 

I USUALLY AT BREAKPOINT, FAULTING INSTRUCTION, OR FIRST 
INSTRUCTION IN BLOCK 



a USES A PERMANENT DATA BASE FOR OPERATION 
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THE PROBE ENVIRONMENT 



I LOCATED AT >udd>[user pro ject] > [user name] > [user name] .probe 



I CONTAINS PATH NAMES OF PROGRAMS WITH BREAKPOINTS SET IN THEM 



I IS REFERENCED BY probe WHENEVER 



I A BREAKPOINT IS ESTABLISHED OR FREED 



I A BREAKPOINT IS ENCOUNTERED WHILE A PROGRAM IS RUNNING 



I IF THIS DATA BASE IS DELETED, probe LOOSES INFORMATION ABOUT 
BREAKPOINTS 



I IF probe COMPLAINS ABOUT A "seg_fault" THE DATA BASE MAY BE 
DELETED 



I probe CANNOT FREE ANY BREAKPOINTS THAT HAVE BEEN PREVIOUSLY 
SET 



I TO FREE ANY "LOST" BREAKPOINTS, ONE MUST RECOMPILE THE 
AFFECTED PROGRAM 
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A SAMPLE PROGRAM 



a THE EXAMPLE FOR THIS COURSE 



I IS WRITTEN IN PL/I 



I IS FAIRLY WELL STRUCTURED 



I IS EASY TO READ IF YOU ALREADY KNOW A FORTRAN OR COBOL RELATED 
LANGUAGE 



I HAS SOME BUGS IN IT 



I WILL 3E USED IN THE DEBUGGING SCENARIOS THAT FOLLOW 
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A SAMPLE PROGRAM 



a THE FOLLOWING PROGRAM IS SUPPOSED TO 



I KEEP TRACK OF BACK ISSUES OF MAGAZINES OF A SMALL COMPANY 

I EACH RECORD CONTAINS THE NUMBER OF ISSUES LEFT IN STOCK, HOW 
MANY ARE REQUESTED FOR SHIPPING, AND THE CURRENT COST OF 
PURCHASE 



I PRINT OUT A SUMMARY OF THIS DATA 

I ACCEPT TWO INPUT STRINGS 

I BOTH IN THE FORM OF volume : number 

I SPECIFY THE FIRST AND -LAST ISSUES TO BE SUMMARIZED 
I PRINT OUT EACH RECORD AND CALCULATE RUNNING TOTALS 
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A SAMPLE PROGRAM 



B THE PROGRAM 



check^back__issues : 

proc; 

/********************★********************* 

* declarations for check_back_issues * 

* and its subroutines- * 
********************************** 

del back__issues file; 

del ( f irst^issue , last^issue) char (12); 

del ( f irst^issue^del im, last__issue__del im) fixed bin (24); 

del index builtin; 

del substr builtin; 

del nuraber_of_issues fixed bin; 

del issue fixed bin; 

del 1 issue_reco rd , 

2 current___inventory fixed bin (17), 
2 pend ing__requests fixed bin (17), 
2 cost__of_issue fixed dee (8,2); 

del to tal__nuiriber__pend ing fixed bin; 

del to tal__number_stocked fixed bin; 

del total_stock_value fixed dec (8,2); 

del (current volume, current nuinber) fixed bin; 

del ( last^issue^num, f i rst_issue__num) fixed bin; 

del (sysin, sysprint) file; 

del ( f irst_issue_volume , last_issue_^volume) fixed bin; 
del colon internal static options (constant) 
■ char (1) aligned in it (":"); 

open file (back__^issues) keyed sequential input; 

/*********************************************** 

* get number of the first and last issues * 

* the user wants to check, the form is * 

* volume :number. this routine will split * 

* the components up into issue_volume * 

* and issue_number , and position to that * 

* record in the file. * 
***********************************************/ 

put list ("from (specify vol:num): "); 

get list ( f irst^issue) ; 

put list ("to (specify vol:num): "); 

get list (last issue); 
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A SAMPLE PROGRAM 



first issue deliro = index (f irst_issue , colon); 
last_Tssue_Hel im = index (last__issue, colon); 
f irst_issue___volume = 

substr ( f irst^issue , 1, f Irst^issue^delim) ; 
last^issue^^volume ^ " 

substr (last_issue, 1, last_issue__del im) ; 
f irst__issue_nuin = 

substr ( f irst^issue , f irst^issue^del im) ; 
last^issue^nura = ~ — — 

""substT (last issue, last issue delim); 



call position^f ile (f irst__issue_volurae, 
first issue num) ; 



number of__issues - 

{^*last__issue_volume + last__issue__num) - 
(6*f irst^issue^volume + f irst_issue__num) ; 

do issue = 1 to number_of__issues; 

call print^record (); 
end; ~ 

call pr int^summary (); 

close file (back^issues) ; 

return; 

/********************************* 

* begin support subroutines * 

print__record : 

proc 0; 

/********************************************* 

* this subroutine obtains the next record * 

* from the back_issues file, calculates * 

* some totals, and outputs the current * 

* record in a formatted form, * 

*ieit it *************** -k* *** it* ie it -k **ie*1t ******* 

call get^record () ; 

total^number^pending = 

total__number^pend ing + 
issue_recordTpending_^requests; 

total__number__stocked = 

total_number_stocked + 
issue_record . current^inventory; 

total stock value = 
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A SAMPLE PROGRAM 



total_stock_value + 

( issue_record.current__inventory* 

issue^record .cost__of_issue) ; 

put skip edit {"volume", 
current volume, 
"number""", 
current^number , 

"stocked: " , 

issue^record .current^inventory , 
"outstanding requests;", 
issue^reco rd.pending^requests , 
"cost of this issue:", 
issue record .cost^of issue, 
" .") 

(r (output_f ormat 1)) 
file (sysprint) ; 

return; 

output_f ormat__l : 

format (a(6), x(l), f(3,0), x{l), 

a(6) , x(l) , f (3,0) , skip (1) , x(li) , 

a(8) , x(l) , f (6,0) , x(l) , 

a(21) , x(l) , f (6,0) , x(l) , 

a(19), x(l), p"$$$,$$9v.39", a(l)); 

end print records- 



posit ion^file : 

proc (first^vol, first^num); 

* this subroutine positions the back^issues * 

* file to the record specified by the * 

* first issue specifier given by the user * 

* at the beginning of the program, to * 

* position to the record, we simply read * 

* records we don't want and do nothing with * 

* them. * 
*************************************************/ 



del (first^vol, first^^num) fixed bin; 

do while (first__vol > current_volume) ; 
call get_^record {); 

end; 

do while (first__num > current_number) ; 
call get__record (); 

end ; 
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A SAMPLE PROGRAM 



return; 
end position^f ile; 
get^^recordj proc (); 
del key char (8 ) ; 

* this subroutine reads a record from the * 

* back__issue file into the issue record. * 

* the other necessary information, vol * 

* and num of the issue, was stored in * 

* the record's key, we must extract this * 

* from our internally declared key and * 

* place it in the globally available * 

* current^volume and cur rent__number vars * 
***********************************************/ 

read file { back^issues) 
into ( issue^record) 
keyto (key) ; 

current^volume = substr (key, 1, 4); 
current__number - substr (key, 5, 4); 

return; 

end get^record; 



pr int__summary : 

proc 0; 

/************************************** 

* a simple subroutine, all this * 

* does is print out the totals * 

* calculated by the print^record * 

* subroutine. * 

put skip (2) 

edit ("number of issues stocked:", 

to tal_^number_stocked , 

"number of requests pending:", 

total^number^pend ing , 

"total stock^value : " , 

total stock value, 

".") " 

(r (output_format_2 ) ) 
file (sysprint) ; 

return; 
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A SAMPLE PROGRAM 



output format 2: 

format (a(25), x(l), f(6,0), skip (1), 
a(27) , x(l) , f (6,0) , skip (1) , 
a(18), x(l), p"$$$,$$9v.99", a(l)) 

end pr int^summary; 

end check back issues; 
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SCENARIO ONE: FUNDAMENTAL PROBE 



B SOME PRIMARY probe REQUESTS 

I THE source REQUEST 

I PRINTS SOURCE STATEMENTS 

I USAGE: 
source 
sc 

source <number of lines> 
sc <number of lines> 

• I EXAMPLES: 
source 7 
sc 3 

I THE value REQUEST 

I DISPLAYS THE VALUE OF A SINGLE VARIABLE, AN EXPRESSION, OR 
SECTION OF AN ARRAY 

I USAGE: 

value <expression> 

V <expression> 

value <array cross section> 

V <array cross section> 
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SCENARIO ONE: FUNDAMENTAL PROBE 



I EXAMPLES : 
value X 

value array (1:5) 
value strl .mem2 • elem 

V ptrl -> sorae_based_var 

V ptr2 -> really__big.meml.comp (2) .2 

I SPECIFYING THE EXPRESSION FOR THE value REQUEST 

I MADS FROM PROGRAM VARIABLES, CONSTANT VALUES AND probe 
DEFINED FUNCTIONS 

I PROGRAM VARIABLES MUST APPEAR EXACTLY AS THEY WERE TYPED 

IN YOUR PROGRAM 

loop__count9r (PL/I) 

data-part (COBOL) 
I CONSTANTS SHOULD BE IN A FORM ACCEPTABLE TO YOUR PROGRAM 
-99 
3.2e5 
"abode" 
* STRING' 

I probe MAINTAINS A SET OF BUILTIN FUNCTIONS THAT RETURN 
VALUES TO YOU 

addr - RETURNS THE ADDRESS OF ITS ARGUMENT 

addrel - RETURNS AN ADDRESS RELATIVE TO THE SPECIFICATION 
OF ITS ARGUMENTS 

baseptr - RETURNS THE ADDRESS OF THE BEGINNING OF A 
SEGMENT 

length - RETURNS THE LENGTH OF A BIT OR CHARACTER STRING 
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SCENARIO ONE: FUNDAMENTAL PROBE 



max length - RETURNS THE MAXIMUM ALLOWED LENGTH OF A STRING 

null - RETURNS A SPECIAL INVALID ADDRESS 

octal - RETURNS THE MACHINE REPRESENTATION OF ITS ARGUMENT 

pointer - RETURNS AN ADDRESS BASED UPON ITS ARGUMENTS 

rel - RETURNS THE ADDRESS WITHIN A SEGMENT INTO WHICH ITS 
ARGUMENT POINTS 

segno - RETURNS THE NUMBER OF THE SEGMENT INTO WHICH ITS 
ARGUMENT POINTS 

substr - RETURNS A PORTION OF A CHARACTER OR BIT STRING 
unspec - RETURNS THE BINARY REPRESENTATION OF ITS ARGUMENT 

I AN EXPRESSION CAN CONTAIN OPERATORS 

I FOUR DEFINED WITHIN PROBE 

ADDITION - USE A PLUS SIGN (+) 

SUBTRACTION -USE A MINUS SIGN (-) 

MULTIPLICATION - USE AN ASTERISK (*) 

DIVISION - USE A SLASH (/) 

I ORDER IS MULTIPLICATION AND DIVISION, THEN ADDITION AND 
SUBTRACTION 

I ORDER MAY BE OVERRIDDEN WITH PARENTHESES 

I THE symbol REQUEST 

I SHOWS YOU THE DATA TYPE OF A PROGRAM VARIABLE 

I USAGE: 

symbol <name of variable> 
sb <name of variable> 
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I EXAMPLES: 
symbol x 
sb HYPTN 

I THE quit REQUEST 

I CAUSES YOU TO LEAVE PROBE 

I USED TO GET BACK TO COMMAND LEVEL 

I USAGE: 
quit 

q 

s THE SCENARIO 

I THE PROGRAM BLOWS UP 

I PROBE IS USED TO ASSESS THE DAMAGE 
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r 12s54 0.155 21 I 

check__bacl<__^issues I 

from (specify vol :num) : 1 : 1 I 

to (specify vol:num):2:l I 

Error: conversion condition by >udd>MEDmult>F21>doodle>bad_ 1 

\ccbi$check back^issuesl 540 (line 48) I 

onsource = "^1:", onchar | 

Invalid character follows a numeric field. I 

system handler for error returns to command level j 

r 12:54 0.273 52 level 2 ! 

probe I 
Condition conversion raised at line 48 of check^back_issues I 

\c ( level 7 ) . I 

source I 
f irst^issue^volume = 

" ~" substr ( f ir st^issue , 1, first^issue delim); 

~ ! 

value f irst_issue__d6l im ' 

first issue delim =2 ! 

" ~ ! 

value first__issue j 

first_issue ="1:1 " 1 

value substr { f ir st_issue , 1, first issue delim); I 

"1:" - - , 

symbol f i rst__issue__volume i 

fixed bin (17) automatic I 

Declared in check__back__issues I 

V substr (first issue, 1, first issue delim - 1); ! 



q 

r 07:03 0.591 210 level 2 
rl 

r 07:03 0.045 9 
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I TECHNIQUE 

I INVOKE probe - IT TELLS YOU WHAT HAPPENED 

I FIND THE STATEMENT AT WHICH THE PROGRAM DIED 

I CHECK ALL THE VARIABLES IN THAT STATEMENT 
I NOTE THE IMPLICIT CONVERSION 
I THE SUBSTR BUILTIN WAS THE CULPRIT 



9 YOUR TURN 



I WHAT WAS THE PROGRAMMER TRYING TO DO WITH THE SUBSTRING BUILTIN? 



I HOW WOULD YOU CHANGE THE PROGRAM SO THAT THE IMPLICIT CONVERSION 
SUCCEEDS? . « 

I ARE THERE ANY OTHER STATEMENTS WHERE THIS CONDITION MAY HAPPEN? 
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B AS ERRORS ARE FOUND THEY ARE FIXED 



I MODIFY THE SOURCE ONLY 



I RECOMPILE INTO NEW OBJECT 



I CLEAN UP ANY FILES THAT MAY HAVE BEEN LEFT INCONSISTENT 



1 qedx 










1 rcheck back issues. pll 










1 48 










1 first issue volume = 










1 .+1 ■ 










1 substr (first issue. 


Ir 


f i rst_ 


issue 


del im) ; I 


1 s/)/ - l)/p 










1 substr ( f ir st^issue , 


1, 


f irst__ 


issue^ 


_del im - 1 ) i 


1 w 










1 q 










1 r 07:55 0.549 88 










! pll check back issues -tb -sv2 










1 PL/I 26a 










1 r 07:55 3.317 83 










i r 07:55 0.049 8 










! close file back issues 










i r 07:38 0.082 23 











a RUN THE NEW PROGRAM 



I BE AWARE OF NEW PROBLEMS 
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I MAKE SURE THE OLD PROBLEM IS FIXED 



I LOOK FOR ANY EFFECTS YOUR CHANGE MAY HAVE ON OTHER PORTIONS OF 
THE PROGRAM 

1 r 

! check_back__issues 1 

1 from (specify vol :num) : 1 : 1 j 

I to (specify volsnum):l:4 ! 

I Error: conversion condition by >user_^dir_dir>MEDmul t>F21>do 1 

! \codle>bad_cbi$check_back_issues 1 551 (line 50) I 

! onsource = "1:", onchar = ":" 1 

! Invalid character follows a numeric field. I 

I system handler for error returns to command level i 

I r 07:58 0.367 34 level 2 ! 

1 probe I 

! Condition conversion raised at line 50 of check_back_issues I 

I \c ( level 7 ) . I 

I source 1 

i last__issue_^volume i 

! substr (last^issue, 1, last_issue_del im) ; ! 

! From Pandolf .MEDmult 05/19/81 0759.6 mst Tue : I 

i The handbooks came in today. I have them if you want to see I 

i \cthem. 1 

I sra Pandolf .MEDmult good, be there later I 

1 probe: Unknown request, "sm" I 



B SOME INVALUABLE REQUESTS 

I THE list_requests REQUEST 

I LISTS ALL THE ALLOWED REQUESTS IN probe 

I USAGE: 
1 ist__requests 
Ir 
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list^requests 



Summary of probe requests: 



after, a 
args 

before, b 
call, cl 
continue, c 
continue^to, ct 

declare, del 
display, ds 
execute, e 

goto, g 
halt, h 

help 
if 

input_switch , isw 
language, Ing 
let, 1 

list_help, Ih 
1 ist_buil tins , lb 
list_requests, Ir 
1 ist^var iables , Isv 

modes, mode 
output^switch , osw 
pause, p 
position, ps 

quit, q 

reset, r 
source, sc 
stack, sk 
status, St 
step, s 
symbol, sb 

use 

value, V 
where, wh 

while, wl 



Set a breakpoint after the specified statement. 

Print argument list for procedure. 

Set a breakpoint before the specified statement. 

Call a subroutine. 

Continue after a breakpoint. 

Resume execution from last breakpoint and stop 

at specified statement. 
Create a probe variable. 
Display storage in various formats. 
Execute a Multics command line, usually 

within a break request. 
Continue execution at a specified statement. 
Halt ands re-enter probe. 
Print info files for probe requests. 
Execute probe requests based on specified 

condition. 

Set the I/O switch used for probe input. 

Display or set the current language. 

Change the value of a variable. 

List the available info topics for probe. 

Print a summary listing of all probe builtins. 

Print a summary listing of the probe requests. 

Print type and value of one or more probe 

variables. 
Set probe operation modes. 
Set the I/O switch used for probe output. 
Reset the current breakpoint and halt. 
iMove the probe pointer to a new location 

and display the source. 
Leave probe and return to Multics command 

level . 
Reset breakpoints. 
Display source of program. 
Display the stack. 
Display the status of breakpoints. 
Execute one statement and halt. 
Display information about the specified 

symbol . 

Move the probe pointer to a new location. 
Print the value of a variable or expression. 
Display the current values of the probe 
pointers. 

Execute probe requests while condition 
is. true. 



Type "help" for more information. 
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I THE help REQUEST 

I USAGE: 
help 

help <request> 
help <feature> 

I EXAMPLES: 

help 

help quit 

help EXPRESSIONS 

I THE execute REQUEST 

I ALLOWS A MULTICS COMMAND TO BE PROCESSED WHILE STILL IN probe 

I USAGE: 

execute <cominand line> 
e <command line> 

I EXAMPLES: 

execute "pwd" 
e "list *.pll" 
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I USING THESE REQUESTS 



help execute 

0^/21/19 The "execute" request. 
Syntax: execute STRING 

The contents of STRING are passed to the Multics command pro 
\ccessor . 

This request is chiefly useful in break request list, because 
\ce the more 

convenient escape to the Multics command processor is not av 

\cailable 

then . 

The user can pass an arbitrary line to the Multics command p 

\crocesso r 

by preceeding it with ".." on a new line. 

Examples (6 lines) . More help?no 

execute sm Pandolf .MSDmult good, be there later 

probe (execute) : The Multics command lines must be enclosed 

\cin quotes. 

e "sm Pandolf .MEDmult good, be there later" 
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I FINISHING UP THE CURRENT ERROR 



last^issue^volume = 

subst7 (last^issue, 1, last__issue_deliin) ; 
value substr (last issue, 1, last issue deTim) 

sb last_issue_volume 

fixed "Bin (17) automatic 
Declared in check_^back_issues 
qui t 

r 08:10 2.508 492 level 2 

qedx 

rcheck^back issues. pll 
50,51p 

last^issue^volume = 

.+1 

substr (last^issue, 1, last_issue_del im) ; 

s/)/ - l)/p 

substr { last__issue , 1, last_issue_del im - 1); 

52 , 55p 

f ir st_^i3sue_nuin ~ 

substr ( f ir 3t_issue , f i rst_issue_del im) ; 
last_issue_num = 

substr ( last^^issue , last issue^del im) ; 

53s/)/ + l)/p 

substr (first issue, first issue del im + 1); 
55s/)/ + l)/p - - 

substr (last^issue, last_issue__del im + 1); 

w 
q 

r 08:12 0.423 80 level 2 

pll check_^back__issues -sv2 -tb 
PL/I 26a 

r 08:13 3.524 141 level 2 
rl 

r 08:15 0.046 29 

close file back^issues 
r 08:15 0.051 21 
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a ADDITIONAL USE OF FUNDAMENTAL PROBE REQUESTS 



I SOME USEFUL INFORMATION ABOUT A FAILURE WILL COME INDIRECTLY 
FROM THE probe DIALOGUE 



I NOTE THE USE OF value IN THE NEXT WINDOW 



check__back__ issues 

from (specify vol :num) : 1 : 1 

to (specify vol :num) : 1 : 4 

Error: illegal__procedure condition by >user_dir__dir>MEDraul t 
\c>F21>doodle>bad__cbi$print_record I 675 (line 98) 
(while in pll operator real_to_real___tr ) 
referencing stack_4 16503 (in process dir) 

r 08:15 0.369 42 level 2 

pb 

Condition illegal^procedure raised at line 98 of print__recor 

\cd (level 8) . 

sc 

total stock value = 

"total^stock^^value + 
( issue__record .cur rent inventory* 
issue__record ,cost_of_Tssue) ; 

V issue record .cost^of^issue 
CO st^^oT^ issue = 5 

V issue_record .current^inventory 
curr ent__invento ry = 23 

V to tal_stock_value 

total_stock_value = (invalid decimal data) 
symbol total stock^value 

fixed dec ("§",2) automatic 
Declared in check back^issues 
value octal ( to taT_stock__value) 
040040040040040040040040040 
r 08:19 0.234 33 level 2 

rl 

r 08:19 0.037 2 



Not To Be Reproduced 



2-23 



F21 



SCENARIO TWO: MORE PROBE 



1 qedx 








1 rcheck_back__issues.pll 








1 /del total__stock^value/ 








! del total stock value fixed 


dec 


(8 


f2)j 1 


] s/;/ init (0);/p 








i del total stock value fixed 


dec 


(8 


, 2) mi t (u ) ; J 


1 w " 








1 4 








i . r 08: 20 0.207 24 








1 oil check back issues -sv2 


-tb 






1 PL/I 26a 








1 r 08:21 3.461 233 








1 close file back issues 








1 r 08:22 0.107 69 









I THE illegal__procedure CONDITION ITSELF EXPLAINED LITTLE ABOUT 
THE ERROR 



I THE PL/I STATEMENT WAS TOO COMPLEX TO QUICKLY DETERMINE THE 
IMMEDIATE CAUSE 



I THE value REQUEST UNCOVERED THE 'FACT THAT ONE VARIABLE HAD 
INVALID DATA 



I BECAUSE OF THIS THE VALUE OF total_stock_value WAS 

UNPRINTABLE 



I THE octal BUILTIN FUNCTION ALLOWED US TO LOOK AT THE DATA 
THAT WAS THERE REGARDLESS OF THE DATA TYPE 



I THE PRESENCE OF SPACES (OCTAL 040) INDICATED THAT THE 
VARIABLE WAS NEVER INTIALI2SD (TO OCTAL 060) 
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a BREAKPOINTS 

I AT TIMES, THE PROGRAMMER DESIRES TO VIEW INTERMEDIATE PROGRAM 
VALUES 

I ONE OPTION IS TO PLACE I/O STATEMENTS IN THE SOURCE PROGRAM 
I COSTS TOO MUCH IN TERMS OF RECOMPILES 
I STILL PROVIDES NO WAY TO SUSPEND THE PROGRAM 

I LET THE DEBUGGER DO IT 

I RECOMPILING NOT NECESSARY TO CHANGE DEBUGGING BEHAVIOR 

I THE PROGRAM MAY BE SUSPENDED OR CONTINUE ON AFTER PRINTING 
OUT SOME DIAGNOSTIC 

a PROBE IMPLEMENTATION 

I REVOLVES AROUND THE "BREAKPOINT" 

I A LIST OF ONE OR MORE probe REQUESTS TO BE PERFORMED WHEN A 
STATEMENT IS REACHED 

I LIKE A SMALL PROGRAM FOR EACH STATEMENT 

I MODIFIABLE AT WILL BY THE PROGRAMMER 

I probe BREAKPOINTS CAN BE SPECIFIED TO BE EXECUTED EITHER BEFORE 
OR AFTER AN EXECUTABLE STATEMENT 
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I BEFORSS AND AFTERS ARE SEPARATE BREAKS, AND BOTH WILL BE 
EXECUTED IF ENCOUNTERED CONSECUTIVELY 



I COBOL COMPILER RESTRICTIONS LIMIT COBOL PROGRAMS TO THE USE 
OF BREAKPOINTS BEFORE THE STATEMENT ONLY 



BREAKPOINT REQUESTS 

I THE before REQUEST 

I USAGE: 

before <line> 
b <line> 

before <line>: (<request list>) 
b <rine>: (<request list >) 

I EXAMPLES: 
before 
before 50 



before 5: (value x; value y)~ (Vf^^t \Jft\\J^ Vj Uc<^'t^ 



before: value comp-val 



I NOTES: 

I. IF NO LINE NUMBER IS SPECIFIED, THE CURRENT LINE IS 
ASSUMED 

I IF ONLY ONE REQUEST IS DESIRED AT THE BREAK, THEN THE 
PARENTHESES MAY BE OMITTED 

I IF NO REQUEST IS SPECIFIED, THEN A "halt" REQUEST IS 
ASSUMED, CAUSING THE PROGRAM TO STOP AND PROBE TO BE 
ENTERED 
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I THE Stack REQUEST 

I HOT SPECIFICALLY A BREAK REQUEST 

I DISPLAYS LIST OF ALL PROGRAMS THAT HAVE NOT FINISHED YET 

I ALLOWS YOU TO SEE HOW FAR YOUR PROGRAM HAS RUN 

I SHOWS RELATIONSHIPS BETWEEN PROGRAMS 

I MORE ON STACKS LATER 

I USAGE: 
stack 
sk 

stack <amount> 
sk <amount> 

stack <first frame, araount> 
sk <first frame, amount> 

I EXAMPLES: 
sk 

stack 4 
sk 12,3 

I THE position REQUEST 

I POSITIONS TO AND PRINTS A SPECIFIED SOURCE STATEMENT 
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I USAGE : 

position <label> 
ps <+,-line> 
ps <line> 
ps <"string"> 

I EXAMPLES: 

position do^label 
ps +3 
ps -4 
ps 68 
ps "i^S" 
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a LET'S RETURN TO OUR EXAMPLE 



check_back_ issues 

from (specify vol :num) : 1 ? 1 

to (specify vol:num)sl:4 



volume 1 number 1 

stocked: 
\c of this issue: 

$5.00. 
volume 1 number 2 

stocked: 
\c of this issue: 

$3.00. 
volume 1 number 3 

stocked: 
\c of this issue: 
$3.00. 

Error: size condition by >user__dir^dir>MEDmult>F21>doodle>b 
\cad cbi$pr int__summary 1 1255 (line i'S3) 

PrecTsion of target insufficient for number of integral digi 
\cts assigned to it. 

system handler for error returns to comm3nd level 
r 08:23 0.420 40 level 2 



23 outstanding requests: 



30 outstanding requests: 



27 outstanding requests: 



0 cost 



2 cost 



0 cost 
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probe 

Condition size raised at line 193 of pr int^summary (level 8). 
source 

put skip (2) 

edit ("number of issues stocked:", 

total__number_^stocked , 

"number of requests pending:", 

total^number^pend ing , 

"totaT stock value:", 

total stock_value, 

(r (output_format_2) ) 
file (sysprint) ; 

stack 



15 simple_^command_processor 1 12265 

14 command processor^^I 11070 

13 abbrev_T5335 

12 release^stacki 10031 

11 unclaimed_signal 1 27064 

10 wall!4436 

9 walli4407 error 

8 pr int__summary (line 193) size 

7 check^back^issues (line 70) 

6 simple_command_processor 1 12265 

5 command process© r_l 11070 

4 abbrev_T5336 

3 listen__1 10031 

c uioj«5-;t stare up i^i/i/ 

1 user_init_admin_| 42452 (aim) 
sc ~" 



put skip (2) 

edit ("number of issues stocked:", 

total__number_stocked , 

"number of .requests pending:", 

total^number^pend ing , 

"totaT stock value:", 

total stock value, 

".") ~ 

(r ( output_format_2) ) 
file (sysprint) ; 
V to tal^number^stocked 

number ed = 4. 

positTon " to'Eal_number__stocked =" 
total^number^stocked = 

to tal__number_stocked + 
issue_^record .curr ent^invento ry ; 

before 

Break set before line 95 
qui t 

r 08:27 0.968 317 level 2 
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I THE PROGRAM WILL NOW STOP BEFORE LINE 95 IS REACHED 



I probe IS AUTOMATICALLY INVOKED 



I THE REQUEST LIST IS PROCESSED 



I IN THIS CASE, WE ARE PLACED AT probe REQUEST LEVEL 

I IF THE halt REQUEST WAS NEITHER IMPLICITLY NOR EXPLICITLY 
STATED, EXECUTION WOULD CONTINUE WITH LINE 95 



r 

rl I 

r 08:27 0.041 10 I 

close^file back^issues I 

r 08:28 0.049 17 I 

check_back__ issues I 

from (specify vol :num) : 1: 1 I 

to (specify vol :num) •: 1 : 4 I 

Stopped before line 95 of pr int^record . (level 8) 1 

source I 

total_number__^stocked = I 

to tal_^number__stocked + I 

issue_^record,current^inventory; i 

V to tal_nuraber_stocked ~ I 

to tal__nuinbe restocked = 4.30337e9 I 

symbol total^number__stocked I 

fixed bin (T7) automatic I 

Declared in check back issues I 

q ~ " I 

r 08:30 0.441 115 i 



I TECHNIQUE: 
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I NOTE THE CONDITION: size 

I RESULT TOO BIG TO BE PLACED IN TARGET STORAGE LOCATION 
I DISAGREES WITH THE WAY THE PROGRAMMER THOUGHT TO USE IT 

I FIND OUT WHERE THE VARIABLE IS ASSIGNED 

I SET BREAKPOINT THERE 

I LOOK AT VALUE OF VARIABLE AT THAT STATEMENT 

I THE VARIABLE HAD A RANDOM VALUE IN IT 
I IT WAS NOT INITIALLY SET 

I THIS CARRIED THROUGH UNTIL IT SLEW UP AT THE OUTPUT 
FORMATTING 
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qedx 

rcheck_back_^issues.pll 

/del to tal__numbe restocked/ 

del total number Stocked fixed bin? 

s/;/ init"(0) p/p" 

del total_^number^stocked fixed bin init (0); 
w ~ 

q 

r 08:30 0.256 30 

pll check^back^issues -sv2 -tb 

PL/I 26a 

r 08:31 3.549 111 

close file back__issues 
r 08:31 0,057 8 

check^back__issues 

from (specify vol:num):l:l 

to (specify vol :nLim) : 1 : 4 

volume 1 number 1 

stocked: 23 outstanding requests: 0 cost of 

this issue: 

$5.00« volume 1 number 2 

stocked: 30 outstanding requests: 2 cost of 

this issue: 

$3.00. volume 1 number 3 

stocked: 27 outstanding requests: 0 cost of 

this issue: 

$3.00. Error: size condition by 
>user_dir_dir>MEDmult>F21>doodle>bad_cbi$pr int_summary| 1304 
(line 193) Precision of target insufficient for number of 
integral digits assigned to it^ system handler for error 
returns to command level 
r 08:32 0.467 22 level 2 
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8 YOUR TURN 



I THIS LOOKS LIKE THE SAME 



I LIST THE STEPS YOU WOULD 
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ERROR. IS IT? HOW DO YOU KNOW? 



TAKE TO RESOLVE THIS ERROR. 
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Condition size raised at line 193 of pr int__summary (level 8), 
sc 

put skip (2) 

edit ("number of issues stocked:", 

total_number_stocked , 

"number of requests pending:", 

total_number_pend ing , 

"total stock value:", 

total stock value, 

".") ~ 

(r (output_format_2) ) 
file ( syspr int) ; " 

V to tal__number__stocked 
total_^number_stocked = 80 

V tot'al_number_pend ing 
total__number pending - 4.30337e9 

V to tal__stocl<_value 
total_stock__value = 286 
sb total number__pend ing 

fixed bTn (17) automatic 
Declared in check_^back__issues 

q 

r 08:33 0.386 79 level 2 

qx 

rcheck__bac k___ issues .pi 1 

/del total__number_pend ing/ 

del total number__pend ing fixed bin; 

s/;/ init~(0);/p 

del total_number_pend ing fixed bin init (0); 
w 

q 

r 08:34 0.216 35 level 2 

pll check__back issues -tb -sv2 

PL/I 26a 

r 08:34 3.462 219 level 2 
rl 

r 08:34 0.040 6 

close_file back_issues 
r 08:35 0.042 7 
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a MORE REQUESTS 

I THE after REQUEST 

I SETS UP A BREAKPOINT AFTER A GIVEN STATEMENT IN A PROGRAM 

I OPERATES EXACTLY LIKE THE before REQUEST 

I USAGE: 
after 
a 

after <line>; (<request list>} 
a <line>s (<request list>) 

I EXAMPLES: 
after 
after 100 

a 50: (value x; value y) 

I THE status REQUEST 

I LISTS BREAKPOINTS YOU HAVE SET IN YOUR PROGRAMS 
I USAGE: 
Status 

St 

status <program name> 

St <program natne> 

status <line in current prograni> 
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St <line in current program> 
status -all 
St -all 
status * 

St * 

I EXAMPLES: 
status 

status at 50 
status other-prog 
status -all 

I NOTES: 

"status -all" LISTS ALL BREAKS SET 

"status *" LISTS THE NAMES OF PROGRAMS WITH BREAKS SET 

AN OPTIONAL CONTROL ARGUMENT OF "-long" IS ALLOWED, WHICH 
PRINTS THE PROBE REQUEST LIST ASSOCIATED WITH THE BREAKPOINT 

I THE continue REQUEST 

I ALLOWS THE PROGRAMMER TO RESUME THE PROGRAM AFTER A BREAK 
THAT INVOKED probe 

I USAGE: 
continue 
c 

I EXAMPLES: 
continue 
c 
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a BACK TO THE SCENARIO 



1 check back issues 












! from (specify vol :num) : 1: 1 












i to (specify vol:nura):l 


I 4 










1 volume 1 numoer 1 












! stocked: 23 outstanding 


requests: 


0 


cost 


of 


this issue: i 


1 $5.00. 












i volume 1 number 2 












i stocked: 30 outstanding 


requests : 


2 


cost 


of 


this issue : ! 


1 $3.00. 












1 volume 1 number 3 












1 stocked: 27 outstanding 


requests: 


0 


cost 


of 


this issue: 1 


1 $3.00. 












! number of issues stocked: 80 












1 number of requests pending: 


2 










i total stock value: $286.00. 












! r 08:36 0.264 7 













I A NEW PROBLEM: NOT ENOUGH RECORDS PRINTED OUT 

I WITH NO CONDITION SIGNALLED, BREAKPOINTS ARE THE ONLY WAY TO 
GET INTO PROBE WHILE THE PROGRAM IS RUNNING 

I WITHOUT SETTING TOO MANY BREAKS, ATTEMPT TO STOP THE PROGRAM 
AT APPROPRIATE PLACES AND LOOK AT LOOP VALUES 
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r 
I 

probe check_back_issues I 

Using check_^back__^issues (no active frame) » I 

ps "do issue" I 

do issue = 1 to number of issues; I 

b " " I 

Break set before line 66 I 

quit I 

r 08:39 0.342 137 I 

check_back issues I 

"From {specify vol:num):l:l ! 

to (specify vol:num):l:4 ! 

Stopped before line 66 of check_back__issues . (level 7) I 

V number_of__issues I 
number^of^i'isues - 3 I 

ps " number_of_issues =" j" 

number_of__ issues = I 

(6*last___issue__^volume + last_issue__num) - I 

{6*f ir st__issue_volume + f irst_issue__num) ; I 

V last__issue__volume 1 
last__^issue__volume = 1 I 

V last__issue_num I 
last_i"ssue__num = 4 I 

V f i rst^issue^volume ; v f i rst_issue_num ! 
f ir st__issu6__vol urae = 1 " I 
first issue num = 1 I 



position +2 

call pr int^^record (); 

after 

Break set after line 67 
continue 



Not To Be Reproduced 



2-39 



F21 



ADDITIONAL BREAK CONTROL 



T 

I volume 1 number 1 

I stocked: 23 outstanding requests: 

I $5 .00 . Stopped after line 67 of check__back 

1 V issue 

I issue - 1 

i c 

I volume 1 number 2 

I stocked: 30 outstanding requests: 

I $3 • 00 • Stopped after line 67 of check__back 

i V issue 

i issue = 2 

! c 

I volume 1 number 3 
i stocked: 27 outstanding requests: 0 cost 

i $3. 00. Stopped after line 67 of check^back^issues . 

i V issue 

! issue = 3 

i status 

1 Break exists after line 67 in check_back__issues 

i Break exists before line 66 in cheGk_baGk__issues 

1 c 



number of issues stocked: 80 
number of requests pending: 2 
total stock value: $286.00,. 
r 08:46 1.185 380 



I TECHNIQUE: 



I IDENTIFY THE LOOP THAT PRINTS THE RECORDS 



I SET A BREAK WITHIN THE LOOP AND CHECK THE LOOP VARIABLE 



I LOCATE THE STATEMENT AT WHICH THE LOOP VARIABLE WAS 
INCORRECTLY SET . 



I FIX THE SOURCE 
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2 cost of this issue: 
issues, (level 7) 



of this issue: 
(level 7) 
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qedx 

rc'ueck_^back issues epll 
/number of Tssues/ 
del numBer of issues fixed bin; 
// " 

number of issues = 

s/$/ 1 +/P 

number__of_issues = 1 + 

w 

q 

r 09:09 0.270 80 

pll check_back__issues -sv2 ~tb 
PL/I 26a 

r 09il0 3.668 234 



check___back issues 

from (specTfy volrnum): 1:1 



to (specify vol:num):l:4 

'volume 1 number 1 

stocked : 
\cof this issue: 

$5.00. 
volume 1 number 2 

stocked : 
\cof this issue: 

$3.00. 
volume 1 number 3 

stocked : 
\cof this issue: 

$3.00. 
volume 1 number 4 

stocked: 
\cof this issue: 
$3.00. 



23 outstanding requests: 



30 outstanding requests: 



27 outstanding requests: 



20 outstanding requests: 



0 cost 



2 cost 



0 cost 



1 cost 



number of issues stocked: 100 
number of requests pending: 
total stock value: $346.00. 
r 09:10 0.362 -28 
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I LOOKS GOOD; NOW TEST IT WITH DIFFERENT DATA. 



check^back^issues 

from (specify vol:num): 2:1 

to (specify vol :num) : 3 : 1 

volume 1 number 1 

stocked: 23 outstanding requests: 0 cost of this issue: 
$5.00. 
volume 1 number 2 

stocked: 30 outstanding requests: 2 cost of this issue: 
$3.00. 
volume 1 number 3 

stocked: 27 outstanding requests: 0 cost of this issue: 
$3.00. 
volume 1 number 4 

stocked: 20 outstanding requests: 1 cost of this issue: 
$3.00. 
volume 1 number 5 

stocked: 40 outstanding requests: 0 cost of this issue: 
S 3 » 0 0 • 
volume 1 number 6 

stocked: 35 outstanding requests: 4 cost of this issue: 
$3.00. 
volume 2 number 1 

stocked: 30 outstanding requests: 2 cost of this issue: 
$3.00. 

number of issues stocked: 205 
number of requests pending: 9 
total stock value: $661.00. 
r. 09: 13 0.443 96 
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a ONE MORE BREAK CONTROL REQUEST 

I THE continue_to REQUEST 

I CAUSES probe TO CONTINUE EXECUTING, BUT ONLY UNTIL LINE 
SPECIFIED 

I USAGE : 

continue__to <line> 

ct <line> 

I EXAMPLES J 

continue^to 75 
ct +1 

I NOTES: 

THE FIRST EXAMPLE RESUMES EXECUTION OF THE PROGRAM AND STOPS 
IN probe AT LINE 75 OF THE PROGRAM 

THE SECOND EXAMPLE RESUMES EXECUTION, BUT STOPS BEFORE THE 
NEXT STATEMENT (I.E. EXECUTE ONE STATEMENT); SEE THE step 
REQUEST LATER 
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probe check__back_issues I 

Using check_bacl<__issues (no active frame) . 1 

position posi tion_f ile j 

posi tion^f ile : i 

proc (first vol, first nam); j 

a " *■ ! 

Break set after line 129 I 

status 1 

Break exists after line 129 in check back__issues I 

Q 1 

r 09:20 0,311 120 I 

1 

check__back__ issues ! 

from (specify vol:num): 2:1 1 

I 

to (specify vol:num):3:l i 

Stopped after line 129 of posi tion__f ile . (level 8) I 

V first__vol I 
first_vol = 2 ■ 

V first^num -i 
first_num - 1 1 
ps +3 ° ■ 

end; i 

a 1 

Break set after line 146 i 

continue_to 132 I 
probe (continue to): Using line 144 of check__back_^issues instead.! 

Stopped before Tine 144 of posi tion__f ile . (level 8") ! 

sc I 

do while (first^vol > current^volume) ; ! 

v first__vol 1 

first_vol = 2 I 

V cur7ent_vol ume 1 
current_volume - 4.30337e9 i 
sb current^volume I 

fixed bin (17) automatic i 

Declared in check back issues I 

q " " 1 

r 09:25 0.831 265 ! 
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r 

qedx i 

rcheck_back__issues.pll I 

/del (curr ent__volume/ I 

del (eurrent volume, current^number ) fixed bin; I 

s/;/ init (07;/p I 

del (current_volume, current^number) fixed bin init (0); I 

w i 

q I 

r 09:27 0.288 83 ! 

pll eheek back issues -sv2 -tb I 

PL/I 26a " " j 

r 09:27 3.520 230 I 

close__file back^issues 1 

t 09; 28 0.044 48 I 
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1 check back issues 
















1 from {specify vol:num) 


: 2: 1 












! to (specify vol:num) 


:3:1 














1 volume 2 number 


2 














i stocked: 36 


outstanding 


requests: 


1 


cost 


0 t 


tn 1 s 


issue: I 


! $3.00. 












1 volume 2 number 


3 














1 stocked: 46 


outstanding 


r eques ts : 


•7 

1 


cost 


0 z 


un 1 s 


1 ssue : j 


1 $3.00. 
















! volume 2 number 


4 














1 stocked: 31 


outstanding 


requests : 


0 


cost 


0 I 


un 1 s 


issue: j 


1 $3.00. 
















1 volume 2 number 


5 














1 stocked: 36 


outstanding 


requests : 


U 


cost 


0 z 


un 1 s 


1 ssue : 1 


i $3.00. 












I volume 2 number 


6 














i stocked: 33 


outstanding 


requests : 




cost 


0 z 


uu I S 


1 ssue : 1 


! $3.00. 
















j volume 3 number 


1 














i ' stocked: 47 


outstanding 


requests : 


5 


cost 


of 


this 


issue: 1 


1 $3,00. 
















! volume 3 number 


2 














i stocked: 50 


outstand ing 


requests : 


4 


cost 


of 


this 


issue: 1 


1 $3.00. 
















! number of issues stocked: 279 














1 number of requests pending: 


18 












i total stock value: 


$837.00. 














i r 09:28 0.395 30 

















a TWO MORE BREAK REQUESTS 



I THE reset REQUEST 

I DELETES SPECIFIED BREAKPOINTS 

(RESET BEING A HARDWARE TERM FOR TURNING A SWITCH OFF) 
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I USAGE: 
reset 
r 

reset <location> 
r <location> 
reset < prog ram naine> 
r <program name> 
reset -all 
r -all 
reset * 
r * 

I EXAMPLES: 

reset after 75 
reset 

reset other-prog 
r * 

I NOTES: 

THE "reset *'* and "reset -all" ARE IDENTICAL: THEY BOTH 
DELETE ALL BREAKPOINTS IN ALL PROGRAMS 

I THE Step REQUEST 

I EXECUTES ALL THE INSTRUCTIONS UP TO, BUT NOT INCLUDING, THE 
NEXT STATEMENT 

I USAGE: 
Step 
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s 

I EXAMPLES: 
step 
s 

I NOTES: 

ACTS JUST LIKE EITHER OF THE FOLLOWING: 

Gontinue__to +1 

before +1: (reset; halt) 
IS DEFINITELY MORE CONVENIENT 
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r 

I 

pb check^back^issues I 

Using check__back__issues (no active frame) . I 

ps posi tion^^f ile"" I 

posi tion^f ile: I 

proc (first^vol, first^num); I 

a " j 

Break set after line 129 j 

q 1 

r 09:30 0.247 98 I 

check__back issues I 

from (specTfy vol:num): 2:1 1 

to (specify vol .•iium) •. 3 : 1 I 

Stopped after line 129 of position^f ile. (level 8) I 

sk 8,2 I 

8 position^f ile (line 129) ! 

7 check^back^issues (line 58) I 

sc j 

posi tion_f lie : I 

proc ( f irst___vol , f irst__num) ; ! 

step I 

Stepped before line 144 of posi tion^f ile . (level 3) I 

sc I 

do while (first__vol > current^volume) ; i 

ps "return" I 

return; ! 

b I 

Break set before line 152 1 
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I r 

I status 1 

! Break exists before line 152 in check back_issues I 

I Break exists before line 144 in check__back^issues I 

1 Break exists after line 129 in check__back^Tssues 1 

I reset 144 I 

I Break reset before line 144 in check^back^issues 1 

I continue I 

I Stopped before line 152 of posi tion^f ile . (level 8) 1 

I V current__volume ! 

i current__volume = 2 I 

! V current__number I 

! current__number = 1 I 

I q 1 

I r 09:39 1.492 420 i 

I - i 



Not To Be Reproduced 



2-50 



F21 



ADDITIONAL BREAK CONTROL 



I TECHNIQUE 

I DETERMINE THAT CORRECT NUMBER OF RECORDS ARE BEING PRINTED 
OUT, BUT THAT THE STARTING POINT IS INCORRECT 

I DECIDE THAT THE PROGRAM "position file" IS THE PROCEDURE THAT 
SETS THE STARTING POINT " 



I SET BREAKPOINTS WITHIN " pos i t ion^f i le" TO CHECK THE SETTING 
OF THE STARTING POINT 



I SEE THAT "position file" POSITIONS TO THE FIRST DESIRED 
RECORD ~ 



I CONCLUDE THAT "print record" DOES NOT HAVE TO READ THE FIRST 
RECORD " 
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qx 

rcheck__back_issues .pll 
/call get_record/ 

call get_record {); 

i 

if have used record then 
\f " 
/return/ 

return; 

-1 
a 

have used record = '*l"b; 
\f ~ 
a 

\f 

/posi tion__f ile/ 
posi tion_f ile : 
/return/ 

return; 

-1 
a 

have^used^record = "O'^b; 

\f 

In/dcl/ 

del back_issues file; 

i 

del have used record bit (1) aligned;- 

\f 
w 

q 

r 09:43 0.637 104 

pll check_back_^issues -sv2 -tb 
PL/I 26a 

r 09:43 3.814 183 
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i close file back issues 














1 r 09s43 0.050 29 
















1 check back issues 
















1 from (specify vol:nuin) 


:2:1 












1 to (specify volinum) 


:3:1 














i volume 2 number 


1 














1 stocked: 30 


outstand ing 


requests : 


2 


cost 


of 


this 


i ssue : [ 


1 $3,00. 
















! volume 2 number 


2 














1 stocked: 36 


outstand ing 


T* <arrn <a ^■f* ^ • 
L cv^uc a i> 9 • 


1 


W w 


of 


this 


{ eciiA • 1 
X a a u w • 1 


1 $ no 












1 volume 2 number 


3 














I stocked: 46 


outstand ing 




7 


v« u a u 


n f 


L-ii X a 


i 9 Q n A • 1 
X aa ue < i 


1 $3.00. 












1 volume 2 number 


4 














1 stocked: 31 


outstanding 




0 


^ w O t« 


of 


thi s 


i cciiip • 1 
X a a u w • 1 


I $3.00. 
















1 volume 2 number 


5 














! stocked: 36 


outstanding 


requests : 


0 


cost 


of 


th X S 


1 ss ue : 1 


I $3.00. 












1 volume 2 number 


6 














! stocked: 33 


outstand ing 


requests : 


1 

X 


vj a u 




uxi X a 


1 c CI io • 1 

X aa uc • 1 


I $3.00. 












1 volume 3 number 


1 














1 stocked: 47 


outstanding 


requests: 


5 


• cost 


of 


this 


issue : I 


1 $3.00. 












1 number of issues stocked: 259 












1 number of requests pending: 


16 












I total stock value: 


$777.00.. 














! r 09:44 0.459 14 
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a A FEW MORE COMMANDS 

I THE halt REQUEST 

I CAUSES PROBE TO BE ENTERED AT BREAKPOINT EXECUTION TIME 

I USAGE: 
halt 
h 

I EXAMPLES: 

halt 
h 

I NOTES: 

ONLY USEFUL IF NOT EXECUTING IN PROBE ALREADY 

A BREAKPOINT SET IN THE FORM OF "after" IS REALLY 
"after:halt" 

I THE pause REQUEST 

I ACTS LIKE THE halt REQUEST, BUT ALSO RESETS THE BREAKPOINT 

I USAGE: 
pause 

P 
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I EXAMPLE: 
pa use 

P 

I NOTES: 

LIKE THE halt REQUEST, IS ONLY USEFUL AT A BREAKPOINT 

the BREAKPOINT " after : pause" IS EQUIVALENT TO "after: 
(halt; reset) " 

I THE list^builtins REQUEST 

I LISTS THE BUILTIN FUNCTIONS AVAILABLE FROM WITHIN probe 

I USAGE: 

list__builtins 
lb 

I EXAMPLES: 

1 ist^buil tins 
lb 

I THE list help REQUEST 



I LISTS ALL THE HELP FILES AVAILABLE THROUGH THE probe "help" 
REQUEST 



I USAGE: list_help 
Ih 
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PROBE ODDS AND ENDS 



I EXAMPLES: 
list_^help 
Ih 

NOTES : 

YOU CAN GET MORE THAN JUST HELP ON THE REQUESTS: 
DESCRIPTIONS ARE ALSO PROVIDED FOR THE ARGUMENTS TO probe 
REQUESTS 

a SPECIFYING LINES 

I SEVERAL PROBE REQUESTS ACCEPT LINE NUMBERS AS THEIR ARGUMENTS 
I before 
I after 
■I reset 
I status 

I SPECIFICATION OF A LINE CAN TAKE ON MANY FORMS 

I ABSOLUTE LINE NUMBER 
5 

4-21 

I RELATIVE EXECUTABLE STATEMENT 
+1 
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+ 50 
-5 

I USING LABELS 
get_record 
place (3) 
somewhere, 4 
$100 

I SPECIAL SYMBOLS 
$c 

$c,7 
$b 

$b,3 
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TOPIC III 



Other Source-Level Debugging Commands 3-1 

The trace Command 3-1 

Interaction of the Control Arguments. .... 3-5 

Tracing Example One 3-6 

Other trace Control Requests 3-11 

Trace Example Two 3-14 

The display pllio error Command 3-20 

A display pllio error Example 3-21 



3-i 



Topic III SOURCE-LEVEL DEBUGGING (TRACE) Topic III 

OBJECTIVES: 

Upon completion of this topicr students should be able to: 

1. Add and remove procedures to and from the trace table. 

2. Modify the tracins of a particular procedure in the trace 
t ab 1 e * 

3. Use the trace command to perform metering on selected 
procedures. 

4. Monitor recursion of selected procedures. 



Mult i cs 
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THE TRACE COMMAND 



s trace COMMAND 

I SOURCE-LEVEL, PROCEDURE-CALL MONITOR 

I CAN BE USED WITH PROGRAMS WHICH DO NOT HAVE SYMBOL TABLES 

I CAPABILITIES INCLUDE 

I PRINTING ARGUMENTS AT PROCEDURE ENTRY AND/OR EXIT 

I EXECUTING A MULTICS COMMAND LINE AT PROCEDURE ENTRY AND/OR 
EXIT 

I STOPPING (BY CALLING THE COMMAND PROCESSOR) AT PROCEDURE 
ENTRY AND/OR EXIT 

I CONTROLLING THE FREQUENCY AT WHICH TRACING MESSAGES ARE 
PRINTED 

I WATCHING UP TO 16 STORAGE LOCATIONS FOR CHANGES .AT EVERY 
PROCEDURE ENTRY AND/OR EXIT 

I LIMITATIONS 

I ONLY EXTERNAL PROCEDURES COMPILED BY PL/I OR FORTRAN CAN BE 
TRACED 

I ONLY USER-RING PROCEDURES CAN BE TRACED, NOT SUPERVISOR OR 
GATE PROCEDURES 
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THE TRACE COMMAND 



I A PROCEDURE IN A BOUND SEGMENT CAN BE TRACED ONLY IF ITS. 



I USAGE 

trace -control^args 
OR 

trace procedure_names 
OR 

trace -control^args procedure__names 

I procedure__names GIVE THE PATHNAME OR REFERENCE NAME OF A 
PROCEDURE ENTRY POINT TO BE TRACED 

J irectory__path>entryname 

d irectory__path>entryname$entry_point__name 
ref e rence__narne 

ref 6rence__name$ entry__point_narae 

I control_arg3 CONTROL THE TRACING FUNCTIONS PERFORMED ON THE 
TRACED PROCEDURE 



I OPERATION 

I trace COUNTS 

I HOW MANY TIMES A PROCEDURE IS CALLED (N = NUMBER OF CALLS) 
IN THIS PROCESS SINCE COUNTERS WERE LAST RESET 

I HOW MANY TIMES A PROCEDURE IS MONITORED WHILE A PREVIOUS 
ACTIVATION STILL EXISTS (R = RECURSION DEPTH) 
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THE TRACE COMMAND 



I OPERATION (Continued) 



I trace MONITORS A PROCEDURE CALL 

I WHEN N AND R MEET CERTAIN CRITERIA 

I BY PRINTING MONITORING MESSAGES 

Call N.R of PROCEDURE from CALL ING__P ROC , ap=244 11746. 

Return N.R from PROCEDURE. 

I BY OPTIONALLY PRINTING PROCEDURE ARGUMENTS BEFORE ENTRY OR 
AFTER EXIT 

I BY OPTIONALLY GOING TO Multics COMMAND LEVEL OR INVOKING A 
USER-SPECIFIED PROCEDURE BEFORE ENTRY OR AFTER EXIT 



I MONITORING CRITERIA 

I ARE STORED IN A TRACE CONTROL TEMPLATE (TCT) , AN INTERNAL 
STATIC DATABASE IN THE PROCESS DIRECTORY 

I FOR EACH TRACED PROCEDURE ARE STORED IN TEMF'LATSS 
FASHIONED AFTER THE TCT 

I IN THE TCT ARE PRINTED BY 

trace -template 



I ARE SET BY GIVING A trace COMMAND WITH THE FOLLOWING 
control__args : 

-first F, -ft F 

MONITOR WHEN F<==N 

-last L, -It L 

MONITOR WHILE N<=L 

-every E, -ev E 

MONITOR EVERY Eth CALL (WHEN mod(N,E)=0) 

-before B 

STOP BEFORE ENTERING PROCEDURE IF B"=0 AND mod(N,B)=0 
AND mod(N,E)=0 

-after A 

STOP AFTER EXITING PROCEDURE IF A" = 0 AND mod-(N,A)-0 
AND mod(N,S)=0 
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THE TRACE COMMAND 



-argument AG, -ag AG 

■nn Txt in n r>/ 

mod(N,E)=0 



-in PRINT ARGUMENTS ONLY BEFORE ENTRY 
-out PRINT ARGUMENTS ONLY AFTER EXIT 



inout 

PRINT ARGUMENTS BEFORE ENTRY AND AFTER EXIT 



-depth D, -dh D 

MONITOR ONLY IF R<=D AND GOVERNING IS OFF 



-return__value {onloff}, -rv {onloff} 

PRINT FUNCTION RETURN VALUE AFTER EXIT 



-govern {onloff}, -gv {onloff} 

DISABLE RECURSION DEPTH CHECKING; INSTEAD, PRINT THE 
CALL MESSAGE ONLY WHEN THE RECURSION DEPTH REACHES A 
NEW MAXIMUM. ALSO, STOP WHEN RECURSION DEPTH IS A 
MULTIPLE OF 10 Se A NEW MAXIMUM. 



-meter {onloff}, -rat {onjoff} 

DISABLE MONITORING AND ENABLE PERFORMANCE METERING OF 
THE TRACED PROCEDURES 
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INTERACTION OF THE CONTROL ARGUMENTS 



traet -first 5 -last 12 Hwsry 2 -before 3 -arsumfint 4 



CALLS OF tt 

m 




MONITOR EVERY 
2nd CALL 
{-avtry 2) 



i 



6.1 8.2 10.3 12.4 



STOP BEFORE 
EVERY 3rd CALL 
(iF IT'S MONSTORED) 
(•bafcra 3} 



1 



i 



12 



PRINT INPUT 
ARGUMENTS EV^RY 
4th CALL (IF ITS 
MONITORED) 
(•argumant 4) 



i 



12 
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1 fact_; procedure (n) returrss (fixed dec (12)); 

2 del (n, f, r) fixed dec (12); 



3 if n <« 1 tnen r = 1; 

4 else do; 

5 f = fact_ (n-1) ; 

6 r » f * n; 

7 end; 

8 return ( r) ; 

9 end fact ; 



1 1 


factorial; procedure; i 


1 2 


del 


result fixed dec (12); 1 


1 3 


del 


fact_ entry (fixed dec '12)) returns (fixed dec (12)); 1 


1 4 


del 


n fixed dec (12) ; 1 


! 5 


del 


cleanup condition; • 1 


1 6 


del 


(sysin, sysprint) file; ! 


1 7 
1 8 




open file(sysin) stream input, 1 
f ile ( syspr int) stream output 1 


1 9 




env ( interactive) ; 1 


1 10 




on cleanup close file (sysin), file (sysprint); i 


1 11 




get file (sysin) list (n); 1 


1 12 




do wh ile ( n >~ 0 ) ; 1 


i 13 




result = fact_ (n^ ; ! 


1 14 




put file (sysprint) list (result); I 


1 15 




get file (sysin) list (n); j 


1 16 




end; - 1 


1 17 




close file (sysin), file (sysprint); . 1 


1 18 




end factorial; 1 
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TRACING EXAMPLE ONE 



1 1 


I pll fact 






PL/I 






i -mi 


r 1720 


1. 


381 21,775 143 i 










1 c 
t J 


I pll factorial 1 


1 0 


PL/I 






1 7 


r 1720 


0. 


964 1.332 36 i 


1 0 








i Q 

1 3 


! factorial 




\ 1 fi 
! 1 U 


i 3 






1 1 1 

1 i> X 






6 1 




1 4 






1 X J 






24 1 


1 X 1 


I 5 












120 ! 


! 16 


I 6 






! 17 






720 1 


1 18 


1 10 






1 19 




3628800 i 


1 20 


I -1 






i 21 


r 1721 


0. 


303 0.342 18 i 


! 22 









Not To Be Reproduced 



3-7 



F21 



TRACING EXAMPLE ONE 



1 O "3 
1 Z J 


1 


trace — 


template 








1 O A 




^4 1^ e ^ • 


1, last: S999999999, every: 1, 




1 "5 ^ 
1 ^3 




US Lo r s i 


Q, after: 0^ args: depth: 


777377I?5jJf ! 


1 ^ o 




tn o +• A y • 


off, govern: off 




V dX Lie 


nf f 1 


1 "5 7 




r 1721 


0.067 0,042 6 








t T Q 














1 

1 t, 7 


f 


trace - 


arguments 1 -out 


-» f o t* n T* n 


val Mia 


on I 


1 "^n 




r 1721 


0.038 0.002 1 








I 1 

1 J Jd 














1 9 

1 o ^ 


1 


trace fact 








1 1 1 

1 'J w 




r 1721 


0.155 0.506 22 








! 34 














i 5 


j 


factorial 








1 36 
1 -J u 


1 


5 A/.XV 








1 37 




■ Call 1 


1 of fact__ from 




1 9 3 t=i 
1 ^ -J J f 




1 ft 
1 .3 o 






2 of fact_ from 




an s 

ap - 


^ 's 4 1 0 0 vj U 1 


1 "XOk 
1 J 7 




Call 3 


3 of fact_ from 


£ a C u 1 't J , 


ap - 


"7 4 4 1 1 90 1 
I ft 1 Q X Z U 1 


1 A n 
1 u 




Call 4. 


4 of fact_ from 


f -t- 1 4 

L S U t, 1 H J / 


ap - 


9 A /I 1 <^ 4 A n ! 
Z 'i 4 1 0 '* *i U i 


1 /1 1 




Call 5 


5 of fact_ from 


f a/^t- 1 A "3 
I. aVtf (. 1 rt J , 


ap - 


^ A A \ Cil c.r\ 1 


! /I 0 




Return 


5.5 from fact 








1 J 




ARC 1 


§ 244 16750 = 1 








1 L &. 
1 »* *4 




ARG 2 


@ 24416740 = 1 








1 L ^ 




Return 


4.4 from fact 








1 Afi 
1 's O 




ARG 1 


§ 24416430 = 2 








1 4.7 




ARG 2 


@ 24416420 = 2 








1 1 0 




Return 


3.3 from fact 






1 


1 4Q 




ARG 1 


@ 24416110 = 3 








1 =^ n 




ARG 2 


@ 24416100 = 6 








! S 1 




Return 


2.2 from fact 








1 9 
i 3 




ARG 1 


@ 24415570 = 4 








I c: -3 




ARG 2 


@ 24415560 = 24 








I /I 
1 J *s 




Return 


1.1 from fact 








1 55 




ARG 1 


§ 24415144 = 5 








1 

1 ^ w 




ARG 2 


@ 24415140 = 120 






1 57 






120 








1 58 


! 


-1 










1 59 




r 1721 


0.395 1.632 47 








1 60 
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TRACING EXAMPLE ONE 



61 i trace -every 3 

62 r 1722 0.021 0.000 0 
63 

64 ! trace fact_ 

65 r 1722 0.024 0.000 0 
66 

67 I factorial 

68 1 10 

69 Call 6.1 of fact_ from facto rial ! 235 , ap = 24415254 

70 Call 9.2 of fact_ from fact__i43, ap = 24416100 

71 Call 12,3 of fact_ from fact_l43, ap = 24416720 

72 Call 15.4 of fact___ from fact_!43, ap = 24417540 

73 Return 15.4 from fact_ 

74 ARG 1 @ 244 17530 1 

75 ARG 2 § 24417520 = 1 

76 Return 12.3 from fact_ 

77 ARG 1 § 244 16710 = 4 

78 ARG 2 @ 244 16700 = 24 

79 Return 9.2 from fact_ 

80 ARG 1 @ 244 16070 = 7 

81 ARG 2 § 24416060 = 5040 

82 Return 6.1 from fact__ 

83 ARG 1 @ 24415144 = 10 

84 ARG 2 § 244 15140 = 3628800 

85 3628800 

86 1 -1 

87 r 1722 0.210 0.002 1 

88 
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TRACING EXAMPLE ONE 



89 i trace -status fact_ 

90 fact_: 

91 N s 15 

92 R 0 , max R - 0 

93 F = 1 

94 L = 9999999999 

95 E « 3 

96 B = 0 

97 A = 0 

98 AG = l(o) 

99 D = 9999999999 
100 return_value 
101 

102 r 1722 0.052 0.000 0 

103 

104 ! trace -status * 

105 15.0 fact_ 

106 r 1723 0.027 0.000 0 

107 

108 I trace -reset fact_ -status fact__ 

109 ■ fact_: 

110 N = 0 

111 R = 0 , max R = 0 

112 F = 1 

113 L ^ 9999999999 

114 E = 3 

115 B = 0 

116 A = 0 

117 AG = 1(0) 

118 D = 9999999999 

119 return_value 
120 

121 r 1723 0.055 0.006 2 
122 

123 I factorial 

124 I 4 

125 Call 3.1 of fact_ from fact_i43, ap = 24415560 

126 Return 3.1 from fact__ 

127 ARG 1 @ 24415550 = 2 

128 ARG 2 @ 244 15540 « 2 

129 24 

130 I -1 

131 r 1724 0.103 0.000 0 
132 
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OTHER TRACS CONTROL REQUESTS 
I OTHER trace CONTROL ARGUMENTS 



I CONTROL THE GENERAL OPERATION OF trace 



I INCLUDE 

-Status procedur e__name , -st procedure__name 

PRINTS THE TRACE CONTROL PARAMETERS AND COUNTERS FOR THE 
NAMED PROCEDURE 

-status *, -St * 

LISTS THE PROCEDURES BEING TRACED, THEIR INVOCATION 
COUNTS AND RECURSION DEPTHS 

-reset procedur e_name , -rs pr ocedur e_narae 

ZEROES THE INVOCATION COUNT OF THE GIVEN PROCEDURE 

-off procedur e_name 

STOPS MONITORING THE GIVEN PROCEDURE; PROCEDURE REMAINS 
IN TRACE TABLE AND COUNTING OF INVOCATIONS CONTINUES, 
HOWEVER 

-on procedure__name 

RESUMES MONITORING THE GIVEN PROCEDURE 

-remove procedur e__name , -rm procedur e_name 

STOPS TRACING THE GIVEN PROCEDURE, DELETING ALL COUNTERS 
FOR THE PROCEDURE 



I THE procedure_name OPERAND FOLLOWING CONTROL ARGUMENTS MUST 
have" THE FORM: 

entryname 

entryname$ entry__point__name 
ref erence__nairie 

ref erence_name$ entr y_po int__name 
* 



THE CONTROL ARGUMENT APPLIES TO ALL TRACED PROCEDURES WHEN * 
IS GIVEN 
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OTHER TRACE CONTROL REQUESTS 



1 133 


I 
• 


trace -off fact_ 




1 1 34 




r 1724 0.022 0.000 


0 ' 1 


1 1 








1 1 "9 /f 

1 X 


• 






1 1 37 


1 


12 




1 1 io 




479001500 




i 139 


t 
1 


-1 




1 140 




r 1725 0.072 0.000 


0 1 


1 141 








! 1 /I O 
1 142 


1 


trace -on fact 




I 14 3 




r 1725 0.025 0.000 


0 1 


1 144 








1 1 43 


f 


factorial 




1 1 45 


f 


2 




1 1 47 




Call 18.1 of fact 


from fact 143, ap = 24415420 1 


1 T /I <J 

1 1 4o 




Return 18.1 from fact 1 


1 1 4y 




ARG 1 @ 244 15410 = 


1 1 


j 1 D u 




ARG 2 a 244.15400 = 


J. 1 


1 1 c 1 

1 1 D 1 




2 




1 ICO 
1 1 3 Z 


1 


-1 




1 1 c; "7 
1 Ijo 




r 1726 0c055 0.000 


0 I 


1 ID** 








! ICC 

1 1 bb 


1 


trace -status * 




1 ICC 

1 155 




18.0 fact 




1 TCI 

1 lb/ 




r 1726 0.028 0.000 


0 1 


1 ICO 

i 158 








i i 5.9 


1 


trace -remove fact 




1 loU 




r 1726 0.027 0.002 


'l j 


1 lox 








1 1 0 ^ 


1 


trace -status * 




1 1 b J 




trace: Trace table 


is empty. 1 


1 i o 4 




r 1727 0.036 0.000 


0 1 


1 lob 








i 166 


I 


factorial 




1 ± \j { 


1 


10 




I 168 




3628800 




1 16$ 




-1 




1 170 




r 1727 0.070 0.000 


0 1 
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OTHER TRACE CONTROL REQUESTS 
I OTHER trace CONTROL ARGUMENTS 



I CONTROL THE GENERAL OPERATION OF trace 

-brief, -bf 

SHORTENS THE MONITOR MESSAGES 

-long, -Ig 

PRINTS LONGER MONITOR MESSAGES AGAIN 

-io_switch swi tch_name , -is switch_name 

PRINTS MONITOR MESSAGES ON THE NAMED I/O SWITCH, WHICH 
MUST BE ATTACHED & OPENED FOR STREAM_QUTPUT 

-execute command_line, -ex command_l ine 

EXECUTES THE COMMAND LINE WHENEVER A PROCEDURE IS 
MONITORED 

-stop^proc procedur e_name , -sp procedure_name 

CHANGES THE PROCEDURE CALLED TO STOP BEFORE ENTRY OR 
AFTER EXIT TO THE GIVEN PROCEDURE 



I CONTROL PERFORMANCE MONITORING 

-meter {onloff}, -mt {onloff} 

STARTS/STOPS METERING OF TRACED PROCEDURES 

-total, -tt 

PRINTS PERFORMANCE MEASUREMENTS AND CLEARS THE METERING 
STATISTICS 

-subtotal, -stt 

PRINTS PERFORMANCE MEASUREMENTS BUT DOES NOT CLEAR THE 
METERING STATISTICS 

I WATCH STORAGE LOCATIONS FOR CHANGES AS PROCEDURES ARE TRACED 
AND STOP IF THE LOCATIONS CHANGE 

-watch location, -wt location 

WATCHES THE ONE WORD LOCATION. UP TO 16 LOCATIONS CAN 
BE WATCHED AT ANY TIME. location HAS THE FORM: 

segment_number I offset 



-watch off, -wt off 

TURNS OFF THE WATCH FACILITY 
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TRACE EXAMPLE TWO 

1 .1.. print tt«pll 1 .• 

2 tt: proc; 

3 del ioa_ entry options (variable) ; 

4 del d$ external static; 

5 del mod builtin; 

6 del cleanup condition; 

7 on cleanup begin; 

8 counter = 0; 

9 call ioa_ ("counter initialized back to zero."); 

10 goto bottom; 

11 end; 

12 del counter fixed bin internal static init (0); 

13 counter - counter +1; 

14 call ioa_ ("..*i", counter); 

15 if mod (counter, 5) = 0 then d$ = counter; 

16 call tt; 

17 bottom; 

18 end tt; 
19 
20 

21 ! trace -ft 5 -last 12 -every 2 -before 3 -argument 4 tt 

22 i trace -status tt 

23 tt: 

24 
25 
26 
27 
28 
29 
30 
31 
32 
33 

34 ! trace -template 

35 first: 5, last: 12, every: 2, before: 3, after: 0, args: 4, 

36 depth: 9999999999, meter: off, govern: off, return__value off 

37 I tt 

38 ..1 

39 . .2 

40 ..3 

41 . .4 

42 . .5 

43 Call 6.1 of tt from ttlll3, ap = 24415476 

44 trace: stop before 
4 5 i hmu 

46 

47 Multics MR6.5+, load 32.0/150.0; 40 users 

48 Absentee users 0/4 

49 

50 I start 

51 . .6 

52 , . 7 

53 Call 8.2 of tt from ttill3, ap =s 24416156 

54 Mo arguments. 

55 . .8 

56 . .9 

57 Call 10.3 of tt from ttlll3, ap « 24416636 



N 




0 


R 




0 , max R - 


F 




5 


L 




12 


S 




2 


B 




3 


A 




0 


AG 




4 


D 




9999999999 
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TRACE EXAMPLE TWO 

58 .*10 ... 

59 ..11 

60 Call 12.4 of tt from ttlll3, ap = 24417316 

61 No arguments. 

62 trace: stop before 

63 ! sr 

64 ..12 

65 ..13 

66 ..14 

67 ..15 

68 ..16 

69 ..17 

70 ..18 

71 . ..19 

72 ..20 

73 QUIT 

74 i trace -status tt 

75 tt: 



76 N = 282 

77 R = 4, max R = 0 

78 F « 5 

79 L = 12 

80 S = 2 

81 B = 3 

82 A = 0 

83 ' AG = 4 

84 D = 9999999999 
85 



86 I release -all 

87 counter initialized back to zero, 

88 Return 12.4 from tt 

89 Return 10,3 from tt 

90 Return 8.2 from tt 

91 Return 6.1 from tt 

92 i trace -st-atus tt 

93 tt: 



94 N = 282 

95 R = 0 , max R = 0 

96 F = 5 

97 L = 12 

98 E « 2 

99 B = 3 

100 A = 0 

101 AG = 4 

102 D « 9999999999 
103 



104 I .1 tracerev 

105 b tracerev trace -ft 1 -It 9999999999 -ev 1 -before 0 

106 -after 0 -ag 0 -dh 9999999999 -mt off -gv off -wt off 

107 -return__value off 

108 I tracerev tt 

109 i trace -st tt 

110 tt: 



111 N ^ 282 

112 R = 0, max R = 0 

113 F = 1 

114 L = 9999999999 
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TRACE EXAMPLE TWO 

115 . E = 1 

116 ■ ■ B = ■ 0 ' ' • . . . . 

117 A = 0 

118 • AG * 0 

119 D = 9999999999 

1 20 

121 I list_ref__names d 

122 

123 357 

124 d 

125 I trace -watch 35710 

126 I trace tt 

127 I tt 

128 ..1 

129 ,.2 

130 ..3 

131 ..4 

132 ..5 

133 trace_print_: 35710 = 000000000005 

134 Call 288.6 of tt from ttlll3, ap = 24416556 

135 trace: stop before 

136 I start 

137 _6 

138 ..7 

139 ..8 

140 ..9 

141 ..10 

142 trace_print__: 357 10 ^ 000000000012 

143 Call 293.11 of tt from tt|113, ap = 244110576 

144 trace: stop before 

145 1 start 

146 ..11 

147 ..12 

148 ..13 

149 ..14 

150 ..15 

151 trace_print__: 357 !0 = 000000000017 

152 Call 298.16 of tt from ttlll3, ap = 244112616 

153 trace: stop before 

154 i rl -all 

155 counter initialized back to zero. 

156 I tracerev tt 

157 » trace -st tt 

158 tt: 
159 
160 
161 
162 
163 
164 
165 
166 
167 
168 

169 ! trace -reset tt 

170 I trace -govern on tt 

171 ! tt 







298 


R 




0, max R = 


F 




1 


L 




9999999999 


E 




1 


B 




0 


A 




0 


AG 




0 


D 




9999999999 
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TRACE EXAiMPLS TWO 



172 


Call 1.1 of tt 


from 


command processor 13304 




ap = 244 1 


4600 




173 


. . 1 






174 


Call 2-2 of tt 


from 


ttlll3. ao - 24415056 


175 


. .2 




176 


Call 3.3 of tt 


from 


ttj 113 , ap = 244 1 5376 


177 


. .3 






178 


Call 4.4 of tt 


from 


tt 1 113 , ap = 244 1 5716 


179 


. o4 






ISO 

Ja W V 


Call 5 5 of tt 


^ T om 


ttI113. ao =• 24416236 


181 


. . 5 






182 


tracs orint • 


357 1 0 


- 000000000005 


183 


Call 6" 6 o^~"tt 


from 


ttill3. ao s 244165^6 


184 


. . 6 




185 


Call 7.7 of tt 


from 


ttill3, ap = 24417076 


186 


. .7 






187 


Call 8.8 of tt 


from 


tt!ll3, ap = 24417416 


188 


. .8 






189 


Call 9.9 of tt 


from 


ttl 113, ap = 24417736 


190 


. .9 






191 


Call 10.10 of 


tt from tt|113, ap - 244110256 


192 


trace: stop be 


fore 




193 


i trace —brief 


tt 




194 


i start 






195 


. 1 0 






196 


tr ac e or i n t : 


35710 


— UUOUUUUUUUi^ 


197 


Call Tl.ll of 


tt 




198 


. .11 






199 


Call 12.12 of 


tt 




200 


. .12 






201 


Cal"* 13 13 of 


tt 




202 


. .13 






203 


Call 14.14 of 


tt 




204 


,.14 






205 


Call 15.15 of 


tt ■ 




206 


. . 15 






207 


t rac 8 Dr i n t : 


357 10 


= 000000000017 


208 


Call T6 , 16 ^f 


tt 




209 


. . 16 








ra 11 17 17 of 


tt 




211 

it Jm 


17 






^ X ^ 


fall 18 1 Q of 


tt 




P 13 
^ X J 


. .18 






X ^ 


Call 19.19 of 


tt 




215 


. .19 






216 


Call 20.20 of 


tt 




217 


trace: stop before 




218 


n 1 1 T rn 

V i 






219 


I trace -watch 


off ' 


tt 


220 


i sr 






221 


! ready 






222 


r 1842 9.009 21.098 


724 level 2, 51 


223 








224 


I sr 






225 


. .20 






226 


Call 21.21 of 


tt 




227 


. .21 
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Call 


22 


.22 


of 


tt 


. . 22 










Call 


23 


.23 


of 


tt 


. ,23 










Call 


24 


.24 


of 


tt 












Call 


25 


c 25 


of 


tt 


. . 25 










Call 


26 


» 26 


of 


tt 


e o 26 










Call 


27 


.27 


of 


tt 












Call 


28 


. 28 


of 


tt 


. . 2o 










Call 


29 


.29 


of 


tt 


. .29 










Call 


30 


.30 


of 


tt 


trace: 


stop befo 


QUIT 











TRACE EXAMPLE TWO 

228 

229 
230 
231 
232 

^ *^ 

J J 
234 
235 
236 
237 
238 
239 
240 
241 
242 
243 
244 
245 
246 

247 I rl -all 

248 counter initialized back to zero. 

249 I trace -st tt 

250 tt; 

251 N = 30 

252 R = 0, max R = 30 

253 F = 1 

254 L = 9999999999 

255 E = 1 

256 ■ B =^ 0 

257 A = 0 

258 AG = 0 

259 D 9999999999 

260 govern 
261 

262 ! trace -govern off tt 

263 \ trace -st tt 

264 tt: 

265 N = 30 

266 R = 0, max R = 30 

267 F = 1 

268 L = 9999999999 

269 E » 1 

270 B = 0 

271 A = 0 

272 AG = 0 

273 D = 9999999999 
274 

275 ! trace --reset tt 

276 I trace -st tt 

277 tt: 

278 N = 0 

279 R = 0 , max R = 30 

280 F = 1 

281 L = 9999999999 

282 E = 1 

283 B * 0 

284 A « 0 
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TRAC E EXAMPLE TWO 

285 AG = 0 

286 D = 9999999999 
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THE DISPLAY PLIIQ ERROR COMMAND 
• -a displ'ay_pll-io_error • COMMAND 



I PRINTS ADDITIONAL INFORMATION ABOUT THE MOST RECENT ERROR 
CONDITION SIGNALLED BY THE PL/1 INPUT/OUTPUT FACILITY 

I USAGE 

display_pllio_error 

OR 

dpe 

I PL/1 I/O ERROR CONDITIONS INCLUDE 
I endfile 

I ^^y 

I name 

I recor- 

I transmit 

I undef inedf ile 
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A DISPLAY PLIIO ERROR EXAMPLE 



1 write_file: procedure; 
2 

3 del f file record output; 

4 del reel ehar (10) , 

5 rec2 char (30) varying; 

6 del cleanup condition; 
7 

8 

9 on cleanup close file ( f ) ; 

10 open file ( f) ; 

11 

12 reel = "ABCDEfghij"; 

13 write file (f) from (reel); 
14 

15 ree2 = "abedeFGHIJ" ; 

16 write file ( f ) from (ree2); 

17 

18 close file ( f ) ; 

19 

20 end write file; 



i _ — - — — • p»«wwv,«%^*>,, 

2 

3 del f file record input; 

4 del sysprint file; 

5 del reel char (10); 

6 del (cleanup, endfile) condition; 

7 

8 on cleanup close file ( f ) , file (sysprint); 

9 open file ( f ) , 

10 file (sysprint) output stream env (interactive); 

11 

12 on endfile ( f ) go to DONE; 

13 do while ("l"b) ; 

14 read file (f) into (reel); 

15 put file (sysprint) list (reel); 

16 end; 
17 

13 DONE: 

19 close file (f), file (sysprint); 

20 

21 end read file; 
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A DISPLAY PLIIO ERROR EXAMPLE 



1 I pll read_file -table 

2 PL/I 

3 r 1033 1.353 37.579 272 

4 

5 I pll write__file -table 

6 PL/I 

7 r 1034 0.767 40.527 287 
8 

9 I read_file 
10 

11 Error: undef inedf ile condition 

12 by >udd>F19d>Friedman>read_f ilej 177 (line 9) 

13 occurred while doing I/O on file f 

14 File cannot be opened: call to iox_$open fails. 

15 system handler for error returns to command level 

16 r 1034 0.169 5.250 74 level 2, 16 
17 

18 i display_pll io__error 
19 

20 Error on file f, status code: Entry not found. 

21 Title: vfile_ f 

22 Attributes: input notkeyed record sequential 

23 Permanent attributes: input record 

24 Error in opening or closing f 

25 r 1035 0.069 1.470 37 level 2, 16 

26 

27 I probe 

28 Condition undef inedf ile raised at line 3 of read__fil6. 

29 ! source 

30 open file { f ) , 

31 file (sysprint) output stream env (interactive); 

32 ! quit 

33 r 1035 0.126 5.726 97 level 2, 16 
34 

35 1 release 

36 r 1035 0.028 0.328 17 

37 
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A DISPLAY PLIIO ERROR EXAMPLE 



38 » write__file 

39 

40 Error: undef inedf ile condition 

41 by >add>F19d>?r iedman>write__f ilei 133 (line 10) 

42 occurred while doing I/O on file f 

43 File cannot be opened: 

44 input and output attributes conflict. 

45 system handler for error returns to command level 

46 r 1035 0.140 3.660 60 level 2, 16 

47 

48 I dpe 
49 

50 Error on file f 

51 Title: vfile__ f 

52 Attributes: input output record 

53 Permanent attributes: input output record 

54 Error in opening or closing f 

55 The output attribute conflicts with the input attribute. 

56 r 1036 0.061 1.190 34 level 2, 16 

57 

58 I new__proc 

59 r 1037 0.184 8.372 91 

60 

61 ! write_file 

62 r 1037 0.376 6.532 80 
63 

64 I read_file 
65 

66 Error: undef ined fil e condition 

67 by >udd>F19d>Fr iedman> read_f ilel 177 (line 9) 

68 occurred while doing I/O on file f 

69 File cannot be opened: 

70 input and output attributes conflict, 

71 system handler for error returns to command level 

72 r 1038 0.627 25.122 192 level 2, 16 

73 

7 4 i new__proc 

75 r 1039 0.236 4.830 69 

76 
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A DISPLAY PLIIO ERROR EXAMPLE 



77 1 read_file 

78 ABCDEfghij 
79 

80 Error: record condition 

81 by >udd>F19d>Friedman>read_f ilel 241 (line 14) 

82 occurred while doing I/O on file f 

83 "read into (XX) "? 

84 record in data set larger than variable XX. 

85 Type "start" to continue, 

86 Data will be truncated to record's length. 

87 system handler for error returns to command level 

88 r 1039 0.887 25.244 219 level 2, 16 
89 

90 i dpe 
91 

92 Error on file f, status code: Record is too long. 

93 Title: vfile__ f 

94 Attributes: open input notkeyed record sequential 

95 Permanent attributes: input record 

96 Last i/o operation attempted: read into 

97 r 1040 0.106 3.540 59 level 2, 16 
98 

99 I probe 

100 Condition record raised at line 14 of read__file. 

101 I source 

102 read file ( f ) into (reel); 

103 i V reel 

104 "\000\000\OQQ 

105 abcdeF" 

106 I quit 

107 r 1041 0.368 11.650 192 level 2, 16 
108 

109 I start 

110 \000\000\000 

111 abcdeF 

112 r 1041 0.119 3.492 59 
113 
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h DISPLAY PLIIQ ERROR EXAMPLE 



114 I pr int__attach_table f 

115 f (not attached) 

116 r 1041 0.069 1.640 40 
117 

118 i io_call attach f vfile_ f 

119 r 1041 0.080 3.306 57 
120 

121 i io open f sequential_input 

122 r 1042 0.087 3.422 58 
123 

124 i io read_length f 

125 io_call: len-10. 

126 r 1042 0.039 0.006 2 

127 

128 I io read f 10 

129 io_call: 10 characters returned. ABCDEfghij 

130 r 1042 0.077 1.980 44 

131 

132 1 io read__length f 

133 io_call: len=34. 

134 r 1042 0.032 1.332 36 

135 

136 i io read f 40 

137 io_call: 34 characters returned. \000\000\000 

138 abcdeFGHIJ\400#\4 00\0 00\0 00\000write_f ile 

139 r 1042 0.050 1.980 44 

140 

141 ! io close detach^ f 

142 r 1043 0.045 2.162 46 
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4-i 



Topic XV ADVANCED PROBE REQUESTS Topic IV 

OBJECTIVES! 

Upon completion of this topic* students should be able to: 

1. Use the followins probe re«iuests to aood advantase: 

modes 
if 

lansuase (Ins) 
display <ds> 

90 to (3> 

where (wh) 
use 

call (cl) 
declare (del) 
list>.var iabies (Isv) 



Mul t i cs 
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INTRODUCTION 



MORE ABOUT probe 



I MOST DEBUGGING CAN BE DONE USING THE TECHNIQUES DESCRIBED IN 
CHAPTER TWO 



I THE REQUESTS DESCRIBED HERE GIVE THE USER MUCH MORE CONTROL OVER 

THE PROSE ENVIRONMENT 

I THE CONTROL CAN BE THOUGHT OF AS COVERING DIFFERENT ASPECTS OF 
probe 

I CONTROL OF THE INTERACTION 
I modes 
I if 

I language 
I display 

I CONTROL OF PROGRAM USAGE 
I goto 
I where 
I use 
I call 

I CONTROL OF PROBE VARIABLES 
I declare 

I list variables 
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SCENARIO I_ - MORS PROSE CONTROL 

a NEW REQUESTS 

I THE modes REQUEST 

I ALTERS THE WAY probe INTERACTS WITH THE PROGRAMMER 

I USAGE: 
modes 
mode 

modes <mode type> <mode value> 
mode <mode type> <mode value> 

I EXAMPLES: 

modes prompt on 

mr-»(^£3C; T^ir/^mr^^ c+-r*i»^/-f ^'■rtK* " 

mode value^separator " is equal to " 

I NOTES: 

SUPPORTED MODES ARE: 
error^messages , em 
qualification, qf 
value__pr int , vp 
value^separator , vs 
prompt 

prompt string 
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SCENARIO - MORS PROBE CONTROL 



I THE language REQUEST 

I ALLOWS THE PROGRAMMER TO LET probe INTERACT IN DIFFERENT 

DIALECTS 

I USAGES 
language 
Ing 

language <language> 
Ing <language> 

I EXAMPLES: 
language 
Ing 

language fortran 
I NOTES: 

THE LANGUAGES CURRENTLY SUPPORTED ARE pll , fortran, AND cobol 

I THE goto REQUEST 

I GIVES BETTER ERROR PROCESSING CONTROL 

I USAGE : 

goto <line> 
g <line> 

I EXAMPLES: 
goto 50 
g 1-23 
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SCENARIO - MORS PROBE CONTROL 

g $c 

g $b+2 

I NOTES: 

I A TRICKY RQUEST TO USE 

I COMPILER OPTIMIZATION MAY NOT LET THE goto PERFORM AS IT 

SEEMS IT SHOULD 

I DEFINITELY MORE DEPENDABLE THAN COMMAND LEVEL start 
I THE SCENARIO - BACK TO OUR PROGRAM 
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SCSHARIO I - MORE PROBE CONTROL 



r 13:57 0.332 51 

chec k^bac k_ i ssue s 

from { specif y vol snum) J 1 s 1 
to (speeify vol snam) i 2 : 1 

Error: conversion condition by 

>user_dir_dir>FSOEP>Pandolf>wkd>check_back_issuesj 540 (line 48) 

onsource = "It", onchar = ":" 

Invalid character follows a numeric field. 

system handler for error returns to command level 

r 13:57 0.469 44 level 2 

pb 

Condition conversion raised at 

line 43 of check__back__issues (level 7). 

modes prompt true 

probes language 

Current language is PL/I 

probe: sc 

f irst__issue__volume = 

substr ( f ir st_issue , 1, f irst__issue_del im) ; 
probe: modes prompt false 
modes prompt on 
probe: modes prompt off 

V substr ( f i r st__issue , 1, f i rst__issue_del im) 
"1:" 

let f i rst__is3ue__volume = "1" 

V f i rst__issue__volume 

f i rst_issue__volume =1 

q 

r 14:01 0.431 61 level 2 
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SCENARIO I - MORE PROBE CONTROL 



r 

start ! 

Error: conversion condition by I 

>user_dir_dir>FS0EP>Pandolf>wkd>ch8ci<_back__issuesi 540 (line 48-)- 1 

onsource = "1:", onchar - ~~ | 

Invalid character follows a numeric field, I 

system handler for error returns to command level 1 

r 14:01 0.257 8 level 2 I 

pb 1 

Condition conversion raised at i 

line 48 of check__bac k^issues (level 7). I 

V f irst_issue_del im I 
first__issue delim = 2 ! 
let f irst^i'ssue^del im = 1 I 

V substr Tfirst issue, 1, first issue delim) 1 
"1" - - - I 

q i 

r 14:03 0.244 1 level 2 I 

start ! 

Error: conversion condition by I 
>user_dir_dir>FS0EP>Pandolf>wkd>check_back_i33ues! 540 (line 43) 1 

onsource = "1:", onchar = i 

Invalid character follows a numeric field. 1 

system handler for error returns to command level I 

r 14:03 0.235 0 level 2 I 

pb " 1 
Condition conversion raised at line 48 of check^back^issues I 

( level 7 ) . • I 

V substr ( f ir st^issue , 1, f i r st__issue_del im) I 
" 1 " 1 
goto $c i 

Error: conversion condition by ! 
>user dir dir>?SOE?>Pandolf>wkd>check back issues|550 (line i 

50) - - J 

onsource - "2:", onchar = I 

Invalid character follows a numeric field. ! 

system handler for error returns to command level I 

r 14:05 0.348 2 level 2 i 
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CONTROL OF OUTPUT PROCESSING 



THE PREVIOUSLY DESCRIBED value REQUEST CAN BE USED TO DISPLAY A 
NAMED STORAGE LOCATION 

I THE display REQUEST 

I SHOWS ANY ACCESSIBLE LOCATION ON ONE OF FOUR FORMS 

I USAGE: 

display <address> <format> <count> 
ds <address> <format> <count> 

I EXAMPLES :- 

display var-one octal 2 
ds 260 114430 pointer 1 
ds tmp^strng ascii 12 

I NOTES: 

FOUR MODES ARE AVAILABLE 



octal, o 



ascT-i, a, character, ch, c 



instruction, i 



pointer, ptr, its 
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CONTROL OF OUTPUT PROCESSING 



I THE SCENARIO 



r 14:56 0.325 16 

check_back__issaes 

from (specify vol:num): 1;1 

to (specify vol snum) : 1 : 4 

Error: illegal_procedure condition by 

> user_d ir__dir>FSOEP>Pandolf>wkd>check_back_issues$ printer ecord 1675 
(line 96) 

(while in pll operator real_to_real__tr) 
referencing stack_4 16363 (in process dir) 

r 14:56 1.145 34 level 2 

pb 

Condition il legal_procedure raised at 
line 96 of print_record (level 8) . 
sc 

totai__stock_value = 

to tal_stock_value + 

( issue_record .current_invento ry* 

issue_record.cost_of__i3sue) ; 

V cost__of_issue 
cost_o f_i ssue = 5 

V current inventory 
cur ren t__Tnventory = 23 

V total_stock_value 

total_stock_value = (invalid decimal data) 

V octal ( total_stock_val ue) < 
040040040040040040040040040 ^ »-Ov»v{v-i«/ 

V unspec ( total__stock__value) 

"0 00100 00000010000000010000000 010000000010000000010000 0000 
100 00000 01000 000001 00000 "b 
display total_stock_value a 8 

display to tal_stock__val ue o 2 ^ ^cJ^J^$ 
040040040040 040040040040 

q 

r 14:59 0.928 72 level 2 
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. S.CgNA.RIO .. I.II -.. PROGRAM . MAN.IPUAl,.T.ION 

9 MORE TOOLS 

I THE where REQUEST 

I THIS REQUEST TELLS THE PROGRAMMER THE VALUES OF probe's TWO 
DEBUGGING POINTERS 

I USAGE: 
where 
wh 

where <pointer> 
wh <pointer> 

I EXAMPLES: 
where 
wh sc 

where control 
I NOTES: 

THE TWO POINTER SPECIFICATIONS ARE: 
source, sc 
control, ctl 

THE position AND use REQUESTS CHANGE THE VALUE OF THE SOURCE 
POINTER 

I THE use REQUEST 



Not To Be Reproduced 



4-9 



F21 



SCENARIO III - PROGRAM MANIPUALTION 
I MOVES THE SOURCE POINTER 70 A NEW LOCATION 

I UNLIKE THE position REQUEST, THIS DOES NOT DISPLAY THE FINAL 
LOCATION 

I USAGES 
use 

use <absolute line number> 
use <relative line number> 
use level <number> 
use <prograin name> 
use <character string> 

I EXAMPLES: 

use 

use level 5 
use 138 
use foo 
use +3 

use "vl = 5" 

I NOTES: THIS REQUEST CANNOT 3E USED WITHOUT THE TABLE OPTION 
I THE call REQUEST 

I INVOKES ANOTHER PROGRAM JUST AS IF IT HAD SEEN A SUBROUTINE 
CALL 

I USAGE: 

call <prograni name> (<parameter s> ) 
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■ SCE.NARI..O. . PROGRAM , MANIPUALTION 

I EXAMPLE; 

call my^prog (argl, arg2) 

call com_^err_ (code, "from probe") 

I NOTES: 

probe PERFORMS VALUE CONVERSION AS PART OF THE CALL 
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SCENARIO III. - PROGRAM tMANIPUALTION 



I THE NEXT EXAMPLE 



1 pb check^back^issues 

I Using check_^back_ issues (no active frame) . 

i ps get^record 

i get^record: proc (); 

1 azClk/halt) 

1 Break set after line 153 

1 q 

I r 15:25 0.745 236 

1 check__^back issues 

! from (specTfy vol:num): 1:1 

I to (specify vol:num):l:4 

! 9 get__^record (line 153) 

1 8 print^record (line 88) 

I 7 check_back_issues (line 65) 

t 6 simple_command_processor! 12265 

I 5 command processor^ 1 11070 

I 4 abbrev_T5336 

! 3 listen^! 10031 

1 2 process__overseer 140055 

! 1 user in it admin T424 52 (aim) 

j Stopped after line 153 of get^record. (level 9) 

i where 

i line 153 in get^record (level 9) 

I Control at line 153 of get_^record, 

1 use level 8 

j sc 

! call get__record (); 

I use level 7 

I whe r e 

1 line 65 in check__back_issues (level 7) 

! Control at line 153 of get__record. 

I sc 

I call print^record (); 

! value issue 

1 issue =* 1 

1 c 

I 

I 
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SCENARIO III . - . PROqRAM.. MANIPUALTION . 



volume 1 number 1 

stocked: 23 outstanding requests: 0 cost 

\cof this issue: 

$5.00. 9 get record (line 153) 

8 print^recorH (line 88) 

7 check^back^issues (line 65) 

6 simple'^command^processor 1 12265 

5 command proces"ior 111070 

*4 aootev lojjo 

3 listen"! 10031 

2 procesl overseer 140055 

1 user_inTt_admin_T42452 (aim) 

Stopped after line 153 of get^record. (level 9) 

V issue ~ 
issue = 2 

V number of^issues 
number_oT_^issues = 3 

qui t 

r 17:12 1.216 128 
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. SCENARIO IV - PRQ3S VARIABLES 

a MANAGING YOUR OWN VARIABLES 

I probe ALLOWS THE PROGRAMMER TO SET UP VARIBLES KNOWN TO PROBE 
ONLY, BUT AVAILABLE FOR USE DURING ALL OF probe's PROCESSING 
(BREAKPOINTS, ETC.) 

I ALMOST LIKE HAVING A PL/I INTERPRETER 

I THE declare REQUEST 

I USAGE: 

declare <name> <type> 
del <name> <type> 

I EXAMPLES: 

del pb^counter^l fixed 

del TOTPCT real 

del sum-calc comp-6 -force 

I NOTES: 

THREE DATA TYPES ARE SUPPORTED: 

f VV«^ "^•^ 

fixed, integer, int, comp-6 
float, real 
pointer, ptr 

USE THE -force CONTROL ARGUMENT TO REDEFINE A PROBE VARIABLE 

IF A probe VARIABLE IS THE SAME NAME AS A PROGRAM VARIABLE, 
PREFIX THE probe VARIABLE WITH A PERCENT SIGN 
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SCENARIO .IV ,;r PROBE VARIABLES 

I THE list_variables REQUEST 

I LISTS THE NAMES, DATA TYPES AND VALUES OF probe VARIABLES 

I USAGE: 

list_variables 

X av 

I EXAMPLES: 

1 ist^var iables 
Isv 

I ONE MORE REQUEST 

I THE if REQUEST 

I CONDITIONALLY EXECUTES A SET OF probe REQUESTS 
I USAGE: 

if <cond itional> : (<request list>) 

I EXAMPLES: 

if a=b : (value a; halt) 

if varl = 4.56 : let var2 - 0 

I NOTES: 

CURRENT IMPLEMENTATION ALLOWS FOR ONLY SIMPLE EXPRESSION 
EVALUATION; USE THE help REQUEST TO CHECK ON NEW DEVELOPMENTS 

THE USE OF RELATIONAL OPERATORS IN THE EXPRESSION DEPENDS 
UPON THE LANGUAGE SPECIFIED TO probe 



t To Be Reproduced 



4-15 



F21 



SCENARIO IV- PROBE VARIABLES 



(E.G. PL/I USES FORTRAN USES .eq.) 
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... Sq.ENARXO vI.V...r-., PROBE . . .VARIABLSS- 



I AN EXAMPLE 



1 r 17!l6 0.122 4 , 






1 pb check back^issues^Using check^^back^issues (no active 1 
! frame), ^ps get record /get__record : proc (); declare I 
1 times get recor*^ called fixed /list^var tables 1 
} times get___record called f ixed"^ 0 a: {let 1 
1 times get]^record~called - times^get^record^called + ^;call 1 
j ioa_ ( "get_^record called i times" ,~ " j / I 
1 times get "record called);) Break set after line 153/q/r 1 
1 17:20"0.3^0 85 ~ III 


1 check back issues 

1 lEr om ( spec i f y vol : num) ; 1 : 1 

1 to (specify vol:num):l:4 get^record 


called 1 


times 1 


1 volume 1 number 2 

1 stocked: 30 outstanding requests: 
i this issue: 

1 $3.00.get_record called 2 times 


2 cost 


of 1 


1 volume 1 number 3 

1 stocked: 27 outstanding requests: 
1 this issue: 

i $3 . 00 .get__record called 3 times 


0 cost 


of 1 


1 volume 1 number 4 

1 stocked: 20 outstanding requests: 
i this issue: 

1 $3 . 00 .get^record called 4 times 


1 cost 


of 1 


1 volume 1 number 5 

1 stocked: 40 outstanding requests: 
1 this issue: 
1 $3.00. 


0 cost 


of 1 


1 number of issues stocked: 117 
1 number of requests pending: 3 
1 total stock value: $351.00. 
1 r 17:21 0.660 61 
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■ SCENARIO IV - PROBE VARIABLES 

I THE let REQUEST 

I ASSIGNS THE VALUE OF I'JA EXPRESSION TO A GIVEN VARIBLE 

I USAGE : 

let variable = expression 

let cross_^section = expression 

I EXAMPLES: 

let a =5 let array (2,i) * a - 5 let substr (alpha, 2, 3) = 
"abc" 
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SCENARIO XV ^ PROBE VARIABLES; 



r 

r 18:08 0.156 4 I 

pb check^back^issues Using check^back^ issues (no active I 
frame). ~ps get^record get_record: proc (); ps "return" I 
return? I 

b; if current^volume^last^issue^volume : if 1 
curr ent__number=last_issue_lium :call. ioa__ ("just positioned 1 

Break set before line 175 
list__var iables 

times__get__record_called fixed 4 
let times__get_record__called = 0 

q 

r 18:11 0.386 50 

check back issues 
from TspecTfy vol:num): 1:3 

to ^.( spec if ^_ vol. :num): 1^:6 

'volume ■ I ' number ■ ' 

stocked: 20 outstanding requests: 

'^V>-1'~ i 1- — , 

I o X SO ue : 

$3.00. volume 1 number 5 

stocked: 40 outstanding requests: 

this issue: 

$3. 00. just positioned to last desired record 

volume 1 number 5 

stocked: 35 outstanding requests: 4 cost of 

this issue: 

$3.00. volume 2 number 1 

stocked: 30 outstanding requests: 2 cost of 

this issue: 
$3.00. 

number of issues stocked: 125 
number of requests pending: 7 
total stock value: $375.00, 
r 18:11 0.795 24 



1 cost of 
0 cost of 
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SCENARIO IV - PROBE VARIABLES 



pb check_back_issues 

Using check^back^issues (no active frame) , 
ps get^record 
get^record: proc (); 

a: (let times_get_record^called = times__get_record^called + 1; 
V tiines_get_record^calledT ~ 
Break set after line 153 

q 

r 18:13 0.245 2 



check back issues 

from TspecTfy vol:num): 1:3 

to (specify vol:num):l:6 



1 
2 

3 
4 



volume 



1 



number -.4 

stocked: 20 outstanding requests: 1 cost of .this 



issue: 



$3.0 



0.5 



volume 1 number 5 

stocked: 40 outstanding requests: 0 cost of this 

issue : 

$3.00.6 oust positioned to last desired record 



volume 



1 number 6 

stocked: 35 outstanding requests: 4 cost of this 



issue : 



$3.00.7 



vo 1 urn e 



2 number 1 

stocked: 30 outstanding requests: 2 cost of this 



issue : 
$3.00. 



number of issues stocked: 1 
number of requests pending: 
total stock value: $375,00. 
r 18:14 1.105 6 



125 



7 
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SCENARIO - . PROBE VARiABLSS 



pb check back^issues 

Using check back^issues {no active frame) . 
St °" 

Break exists after line 153 in check back issues 
Break exists before line 175 in checTc__bac1<_ issues 

ps 153 

get_recordj proc {); 

St at 153 

Break exists after line 153 :let times get^reeord_^ealled - 
times_get_record_^called + 1; v times_^get_record__called 

a: (let times__get^record^called = times^get^record^called + 
l;call ioa_ ( " g e t__7ec o rd called '*d times'''*, 

times__get_7ecord_called) ) 
Break set after line 153 
ps 1 

check_back_issues : 
proc ; 

a 

,Br.eak.„s,ejt .§.f ter....l ine .^,1.,,. ......... 

•a sle.t .times_^getJ^record-_called = 0. 
Break' set after iirie' i 

q 

r 13:17 0.450 2 
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MULTICS USER RING RUNTIME STRUCTURES 5-1 

Introduction 5-1 

Supervisor Segments 5-3 

The Stack Segment - stack^n 5-6 

The area. linker Segment 5-11 

Getting Space for Program Variables . 5-23 
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Tdpic V MULTICS USER-RING RUNTIME STRUCTURES Topic V 

objectives: 

Upon completion of this topicr students should be able to: 

1. Describe some of the ways in which processes can be 
inadvertently destroyed. 

segments : 

dses 

kst 

pds 

stack. 1 - stack. 7 (as appropriate) 
:..Cuni«|ue .area. 1 i nicer □ 

3. Describe the format of the following structures: 

linkage offset table (LOT) 
internal static offset table (ISOT) 
ref erence-.name-table (RNT) 

4. Name the sections of a standard Multics object sesment and 
give the functions of each. 
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INTRODUCTION 



a INTRODUCTION 



I THERE IS NO CENTRALIZED LOCATION FOR ALL PROGRAM SUPPORT TABLES 
AND DATA IN MULT ICS 

I NATIVE MULTICS USES SEVERAL SEGMENTS TO MANAGE RUNTIME 

INFORMATION 

I MOST ARE FOUND IN THE PROCESS DIRECTORY 

I THE PROCESS DIRECTORY IS CREATED FOR A USER AT LOGIN TIME 
I IT IS PART OF THE HIERARCHY, JUST AS THE HOME DIRECTORY IS 
I IT IS. GIVEN A SHRIEK NAiME. AS ITS . IDENTITY. 

I THESE TABLES ARE MODIFIABLE BY PROGRAMS IN A PROCESS 

I THEIR MISUSE IS THE MAIN CAUSE OF PROCESS FAILURE 



ot To Be Reproduced 



5-i 



F21 



.tNTR0nUCTX0l4 



r 04:38 0.163 1 
pd 

>process dir_dir> IBXNCwXCBBBBBBB 
r 04:38 0.044 0 

cwd [pd] 

r 04:38 0.047 0 

list 



Segments 


- 7, Lengths = 0^ 




rew 0 


I BBBJLFKcGzxlDq . temp 


.0326 


rew 0 


I BBBJLFKcGxPLpJ .area 


.1 inker 


rew 0 


stack^4 




re 0 


pit "" 




0 


pds 




0. 


. l^s-t.. 




0 


. dseg . 





r 04:38 0.196 0 
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SUPERVISOR SEGMENTS 

a dseg 

I DESCRIPTOR SEGMENT 
I RESIDES IN RING 0 

I USED BY THE HARDWARE TO CALCULATE MEMORY ADDRESSES 
I IS NOT ACCESSIBLE TO THE USER 

8 kst 

I KNOWN SEGMENT TABLE 
I RESIDES IN RING 0 

a IS NOT ACCESSIBLE TO THE USER 

I IS USED INDIRECTLY BY VIRTUAL MEMORY OPERATIONS 

I IS AN ARRAY OF BLOCKS, EACH BLOCK CONTAINING INFORMATION 
ABOUT EACH SEGMENT THE PROCESS IS CAPABLE OF REFERENCING 
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SUPERVISOR SEGMENTS 



I FOR A SEGMENT TO BE USED IN A PROCESS (E.G. PRINTED, EDITED, 
EXECUTED) IT MUST HAVE AN ENTRY IN THE kst 



I IF A SEGMENT HAS AN ENTRY IN THE kst IT IS CONSIDERED "KNOWN" 



I PROCESS DATA SEGMENT 

I RESIDES IN RING 0 

"I CONTAINS MANY THINGS THE. SUPEBVISOR . WANTS TO KNOW ABOUT.. YOUR 
•PROCE'SS'' 

I YOUR PROCESS ID 
I YOUR USER ID 

I PROCESSOR INFORMATION FOR FAULT AND CONDITION PROCESSING 
I RING INFORMATION 
I MORE 

I NOT ACCESSIBLE TO THE USER 
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SUPERVISOR SEGMENTS 
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THE STACK . SSGMENt. - STACK N 

USER STACK 
I FUNCTION 

I IS THE BACKBONE OF THE MULTICS PROGRAMMING ENVIRONMENT 

T r» nxi rn TV TTkie ^rAomiTc? TtAnrcc? nr\T-Kjrn-e>-oc tv xtrv nAT'A 

I USED TO DEFINE THE REST OF THE PROGRAMMING ENVIRONMENT 

I THE STACK IS DIVIDED INTO TWO FUNCTIONAL PARTS 

I AT THE BEGINNING OF THE STACK IS THE STACK HEADER 

t THE HEADER" CO'NTAll^S- 'POINTERS OF' ALL TABLES US-ED' 

I AT SOME POINT INTO THE STACK SEGMENT (DEPENDING ON THE STACK 
ITSELF) ACTIVATION FRAMES WILL BE FOUND 

I EACH FRAME CONTAINS INFORMATION ABOUT VARIABLES OF A 
CURRENTLY ACTIVE (CALLED, BUT NOT YET RETURNED) PROGRAM 

I THE SIZE OF THE STACK IS NOT PREDICTABLE, BECAUSE AS PROGRAMS 
ARE CALLED AND RETURN THE STACK WILL GROW AND SHRINK 
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THE STACK SEGMENT - STACK N 




POINTER 
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• THE STACK SEGMENT - STACK N 



S THE LINKAGE OFFSET TABLE = THE LOT 



I IS USED BY THE DYNAMIC LINKER AND BY PROGRAMS TO FIND THEIR 
LINKAGE INFORMATION 



I IS QUITE SIMPLY AN ARRAY OF ONE WORD ADDRESSES SHOWING WHERE 
VARIOUS LINKAGE SECTIONS ARE 



I TO FIND OUT WHERE THE LINKAGE INFORMATION FOR A PROGRAM (CALL 
IT foo) , FIRST OBTAIN ITS SEGMENT NUMBER 



I COUNT UP THAT MANY WORDS FROM THE BEGINNING OF THE LOT AND 
THE WORD AT WHICH YOU ARRIVE CONTAINS THE ADDRESS OF foo'S 
LINKAGE INFORMATION 



'l ''the' 'Ld'^ ■■ HAS" Xn" INITIAL' SIZE OF 512 WORDS ' "AND " IS ACTUALLY 
OVERLAID UPON THE BEGINNING OF THE STACK 



a THE INTERNAL STATIC OFFSET TABLE - THE ISOT 



I THE ISOT CONTAINS ONE WORD ADDRESSES OF THE STATIC SECTIONS OF 
ALL THE ACTIVE PROGRAMS 



I IT TOO IS AN ARRAY OF THESE ADDRESSES 



I TO FIND THE LOCATION OF SOME PROGRAM'S STATIC SECTION, ONE 
COUNTS UP ITS SEGMENT NUMBER WORTH OF WORDS AS IN THE LOT 
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THE STACK SEGMENT - STACK N 



I THE SIZE OF THE ISOT IS ALSO 512 WORDS LONG AND IT IS FOUND 
RIGHT AFTER THE LOT ON THE STACK 



I BECAUSE OF THE LOT AND ISOT, THE FIRST STACK FRAME USUALLY 
BEGINS RIGHT AFTER THE ISOT 
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^ POINTER 



POINTER 
POINTER 

POINTER 



POINTER 

POINTER 
POINTER 

POINTER 

POINTER 

POINTER 

POINTER 
POINTER 

POINTER 
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THE ARE A. LINKER SEGMENT 



a THE COMBINED LINKAGE AREA 



I AS WILL BE SEEN IN DYNAMIC LINKING, SOME INFORMATION FROM AN 
OBJECT SEGMENT NEEDS TO BE COPIED OUT INTO A WRITSABLE AREA 



I THE COMBINED LINKAGE AREA IS ONE OF THE TWO AREAS THAT HOLD THIS 
COPIED DATA 



I THE COMBINED LINKAGE AREA IS A PL/I TYPE AREA - A MANAGED POOL 
OF STORAGE FOR ALLOCATING AND FREEING DATA 



I HISTORICALLY THE COMBINED LINKAGE AREA WAS A PHYSICALLY SEPARATE 
AREA APART FROM OTHER RUNTIME AREAS. 



I NOW IT IS JUST A "SYNONYM" FOR THE area. linker 



I THEREFORE THE WHOLE area. linker CAN BE THOUGHT OF AS THE 
COMBINED LINKAGE AREA 



a THE COMBINED STATIC AREA 



I MODIFIABLE STATIC DATA IS MAPPED OUT IN THE OBJECT SEGMENT WHEN 
IT IS CREATED, BUT NEEDS TO BE MODIFIED 



I TO PREVENT THE MODIFICATION OF THE OBJECT ITSELF, THE STATIC 

DATA TEMPLATE IS COPIED FROM THE OBJECT TO THE COMBINED STATIC 

SECTION (COMBINED BECAUSE IT IS COMBINED WITH THE STATIC 
SECTIONS OF OTHER PROGRAMS) 
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THE AREA. LINKER SEGMENT 




FREE 
BLOCKS 



0 



ADDR 


ADDR 


ADDR 


ADDR 1 ADDR 




i 

ADDR ( ADDR ' 


ADDR 


1 ' 

ADDR j ADDR 


ADDR 1 
1 1 


1 

ADDR j ADDR 


ADDR 


ADDR j ADDR 

« 


ADDR 1 

! 


Q 


0 


SIZE 


KWM j FIRST 


LG.BK. 



VERSION 
TWO 
AREA 
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THE AREA. LINKER SEGMENT 



I THE COMBINED STATIC AREA IS AGAIN A PL/I TYPE AREA 



I THE COMBINED STATIC AREA IS ANOTHER SYNONYM FOR THE area. linker 
SEGMENT 



a THE REFERENCE NAME TABLE - THE RNT 



I THE REPOSITORY FOR A SET OF ATTRIBUTES' CALLED REFERENCE NAMES 



I A REFERENCE NAME IS AN ATTRIBUTE OF A SEGMENT FOR PROGRAMMING 
PURPOSES 



I a' REFERENCE "name ' EXISTS ONLY WITHIN A PROCESS - IT IS NOT 
PERMANENT ■" 



I IT IS A SYNONYM FOR A SEGMENT THAT IS THE OBJECT OF A SEARCH 



I IT MAY OR MAY NOT BE RELATED TO THE ACTUAL NAME OF THE 
SEGMENT 

I IT. IS CREATED IMPLICITLY OR EXPLICITLY 

■ I WHEN A PROGRAM IS CALLED IT IS" GIVEN A REFERENCE NAME 

I WHEN THE RING 0 initiate PROGRAM IS CALLED (THROUGH A 
GATE, OF COURSE) 

I THE RNT ALSO MAINTAINS THE ASSOCIATION BETWEEN A REFERENCE NAME 
AND THE SEGMENT NUMBER OF A SEGMENT 
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THE : AREA ..h IN-KSR .SEGMENT 



I THE RNT IS IN THE FORM OF A RATHER INVOLVED SERIES OF LINKED 
LISTS 

I THE RNT IS DEFINED BY A HEADER WHICH CONTAINS TWO HASH 
TABLES, ONE FOR SEGMENT NUMBERS AND ONE FOR REFERENCE NAMES 

I EACH ENTRY IN THE RNT IS IN TWO LINKED LISTS - A REFERENCE 
NAME LIST AND A SEGMENT NUMBER LIST 



I THE RNT RESIDES IN THE MIDDLE PORTION OF THE area. linker SEGMENT 



I IT MANAGES ITS OWN AREA IN THIS SEGMENT 



H 'THE USER' FRES"AREA 



I USED FOR ALLOCATING CONTROLLED Ar.D SOME BASED VARIABLES, FOR 
FORTRAN COMMON AND FOR COBOL DATA 



I OBVIOUSLY, BY NOW, IT IS A PL/I AREA 



I THE USER FREE AREA ALSO IS A "SYNONYM" FOR THE area. linker 
SEGMENT 



I TO RUN A PROGRAM THE USER MUST 

I CREATE AN OBJECT SEGMENT ACCEPTABLE TO THE MULTICS LINKERS 
I CALL THE PROGRAM 
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THE AREA « LINKER SEGMENT 



COMBINED STATIC AS2A 



IHTESNAL 
STATIC 
SECTION 



ISOT "f 



LOT 



LINKAGE 
SECTION 



mi 



coboL_cancroL_daca_ 




axe 




prog 





DIRECTORY 



STACK 



SYSTEM FREE AREA 
(gec_3y8Cea_free_area _) 



REGISTERS 
CALLING HISTORY 

AUTOMATIC 



STACK 
HEADER 



BASED DATA- 
IN Alt AREA 



ASSIGNED LINKAGE AREA 
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5A5SD Da?a- 

IN AN AREA 



COBOL 
RL'N UHl 



INFO 



exc 



prog 
prog.pU 



patonames 



EXT. STATIC & 
COMMON 3L0CKS- 
PES PROCESS 



EXTERNAL 



DATA 
CONTROL 
, INFO 



CONTROLLED 
INTERNAL 



1 



CONTROLLED 
EXTERNAL 



:osoL program 

DATA 



BASED DATA- 
NO ASEA 



BASED DATA- 
IN I/O BUFFER 



SOURCE 
PROGRAM 



prog.pll 



OBJECT 
PROGRAM 



prog 



EXTERNAL STATIC 
AND COMMON BLOCKS- 
PERMANENT 



exc 



Not To Be Reproduced 



5-15 



F21 



. THE AREA ..LINKER SSG.MENT 

T FROM ANOTHER PROGRAM 

call prog$entry ()? 
I OR, BY INVOKING IT AT COMMAND LEVEL 

prog$entry 

I THE COMMAND LEVEL INVOCATION DOES NOT CALL IN THE DYNAMIC 
LINKER, WHILE THE CALL STAEMENT MAY 

I THE OBJECT SEGMENT FUNCTIONS TO 

I PROVIDE INSTRUCTIONS AND DATA IN THE MACHINE'S LANGUAGE 

I INSTRUCTIONS ARE CURRENTLY IN L68 MACHINE CODE 

I THE DATA IS PROVIDED FOR THE MULTICS LINKER, PRELINKER, 
BINDER, AND DEBUGGERS 

I COMPOSED -OF 7" SECTIONS 

I TEXT SECTION 

I DEFINITION SECTION 

I LINKAGE SECTION TEMPLATE 

I STATIC SECTION TEMPLATE (OPTIONAL) 

I SYMBOL SECTION 

I OBJECT MAP 

I OBJECT MAP POINTER 
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I TEXT SECTION 

I PURE PART OF AN OBJECT PROGRAM 

I CONTAINS: 

I INSTRUCTIONS (NO SELF-MODIFYING INSTRUCTIONS) 
I ENTRY SEQUENCES 
I READ-ONLY DATA 

I ' DEFINITION SECTION 

I NONEXECUTABLE, READ-ONLY SYMBOLIC INFORMATION 
I USED FOR DYNAxMIC LINKING 
• I . USED FOR SYMBOLIC DEBUGGING . 

I CONTAINS 

I DEFINITIONS 

I OFFSETS OF NAMED ENTITIES IN TEXT AND OTHER SECTIONS 

I DEFINITION HASH TABLE (OPTIONAL) TO EXPEDITE THE LINKER'S 
SEARCHES 

I SYMBOLIC NAMES OF EXTERNAL REFERENCES 
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THE -&bea:;^«^er segment 



I LINKAGE SECTION TEMPLATE 

I INITIAL CONTENTS OF THE IMPURE, NONEXECUTABLE PART OF A 
PROGRAM 

I USED FOR DYNAMIC LINKING 



I CONTAINS 

I UNSNAPPED LINKS TO EXTERNAL REFERENCES 

I DATA ALLOCATED ONCE PER-PROCESS (INTERNAL STATIC DATA) 

I COPIED INTO COMBINED LINKAGE AREA IN THE PROCESS DIR WHEN 
OBJECT SEGMENT IS FIRST REFERENCED 
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THE ARE A. LINKER SEGMENT 



I STATIC SECTION TEMPLATE 



I THE INITIAL CONTENTS OF IMPURE, NONEXECUTABLE DATA FOR OBJECT 
PROGRAM 



I DATA IS 

I ALLOCATED ONLY ONCE PER PROCESS 
I INITIALIZED ONLY ONCE PER PROCESS 



I USUALLY INCLUDED AS PART OF LINKAGE SECTION UNLESS THE 
-separate_Static CONTROL ARGUMENT IS USED WHEN COMPILING THE 
PROGRAM 



I COPIED INTO COMBINED STATIC AREA IN PROCESS DIR WHEN OBJECT 
SEGMENT IS FIRST REFERENCED 
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THE AREA .LINKER SEGMENT 



I SYMBOL SECTION 
I IS PURE 

I CONTAINS INFORMATION NOT BELONGING IN OTHER SECTIONS 
I USED FOR SYMBOLIC DEBUGGING 

I USED FOR OBJECT PROGRAM STATUS COMMANDS (SUCH AS pli) 
I INFORMATION DOCUMENTING CREATION OF OBJECT PROGRAM 
I RELOCATION INFORMATION 

I SOURCE SYMBOL NAMES AND STORAGE LOCATIONS (PRESENT ONLY IF 
-table OPTION SPECIFIED) 

I NOTE J IN THE CASS OF BOUND OBJECT, THIS SECTION MIGHT BE 
FURTHER STRUCTURED INTO A THREADED LIST OF VARIABLE LENGTH 
•■ ■ SYMBOL BLOCKS' 
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THE AREA. LINKER SEGMENT 

I OBJECT MAP 

I DEFINES THE LOCATION (OFFSET) AND LENGTH OF OTHER SECTIONS 

I DEFINES OBJECT SEGMENT FORMAT 

I SINGLE (UNBOUND) OBJECT PROGRAM, OR 

I SEVERAL OBJECT PROGRAMS, BOUND TOGETHER 

I OBJECT MAP POINTER 

I AN 18-3IT OFFSET IN THE UPPER HALF WORD OF THE LAST WORD IN 
THE OBJECT SEGMENT 

I GIVES LOCATION OF OBJECT MAP, RELATIVE TO BASS OF OBJECT 
SEGMENT 

I FOUND USING THE BIT COUNT 
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THE AREA. LINKER- SEGMENT 
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THE ARE A. LINKER SEGMENT 
GETTING SPACE FOR PROGRAM VARIABLES 

B CONSTANTS 

I CONSTANT DATA VALUES, KNOWN ONLY TO ONE PROGRAM 
I DECLARATION 

I PL/1: del con fixed bin internal static options ( constant) 

initial ( 3 ) ; 

I COBOL: CONSTANT SECTION. 

77 CON; PIC IS 99; VALUE IS 3. 

I FORTRAN: parameter con=3 

I LOCATION 

I IN THE TEXT SECTION OF THE PROGRAM 

I ALLOCATED AND INITIALIZED 

I ONCE BY THE COMPILER, WHEN THE SOURCE PROGRAM IS COMPILED 

I FREED 

I NEVER 
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THE ARE A. LINKER , SEGMENT 
GETTING SPACE FOR PROGRAM VARIABLES 

a INTERNAL STATIC 

I PER PROCESS DATA, KNOWN ONLY TO ONE PROGRAM 

I DECLARATION 

I PL/1: declare is internal static; 
I FORTRAN; save is 

I LOCATION 

I IN. INTERNAL. STATIC SECTION OF PROGRAM,- WHICH. IS THEN COPIED 
. TO' [unique] .area .linker 

I NOTE: SUCH VARIABLES CAUSE THE SIZE OF THE OBJECT TO GROW 

I ALLOCATED AND INITIALIZED 

I FIRST TIME OBJECT SEGMENT IS CALLED IN THE PROCESS BY COPYING 
OBJECT'S LINKAGE SECTION (OR SEPARATE STATIC SECTION) 

I FREED 

I WHEN PROCESS TERMINATES, OR WHEN OBJECT SEGMENT IS EXPLICITLY 
TERMINATED (terminate COMMAND) 
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THE ARSA«LINKSR SEGMENT 
GETTING SPACE FOR PROGRAM VARIABLES 

a AUTOMATIC 

I PER PROGRAM-ACTIVATION DATA, KNOWN ONLY TO ONE PROGRAM 

I DECLARATION 

I PL/1: declare a automatic; 
I FORTRAN: automatic a 

I LOCATION 

I "ALLOCATED" -IN STACK FRAME WHEN FRAME IS PUSHED 

I ALLOCATED AND INITIALIZED 

I EACH TIME PROGRAM IS CALLED 

I FREED 

I WHEN PROGRAM RETURNS 
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THE AREA-; LINKER- SEGMENT = 



GETTING SPACE FOR PROGRAM VARIABLES 



EXTERNAL STATIC - PER PROCESS 



I PER PROCESS DATA, SHARED BETWEEN PROGRAMS, STORED IN TEMPORARY 
SEGMENTS IN THE PROCESS DIRECTORY 



I DECLARATION 

I PL/1: declare e external static; 



I FORTRAN: common b,c 

common /e/b,c 



"I " LOCATION 

I ALLOCATED IN USSR FREE AREA 

I ALLOCATED AND INITIALIZED 
I WHEN FIRST REFERENCED 

I FREED 



I WHEN PROCESS TERMINATES, OR EXPLICITLY (SEE 

r eset__external_var iables AND delete external variables 
COMMANDS ) " 



t To Be Reproduced 



5-26 



F21 



THE AREA. LINKER SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



EXTERNAL STATIC - PERMANENT 



I PERMANENT DATA, SHARED BETWEEN PROGRAMS, STORED IN USER-SUPPLIED 
SEGMENTS 



I DECLARATION 



I PL/1: declare ext$ external static, 

ext$e external static; 



I FORTRAN: common /9xt$/b,c 
common /ext$e/b,c 



I .LOCATION . , .- ; 

I IN PERMANENT SEGMENT ext, FOUND BY LINKER (USING OBJECT 
SEARCH RULES) 

I SEGMENT MUST EXIST PRIOR TO EXECUTION 



I ALLOCATED AND INITIALIZED 

I WHEN SEGMENT ext IS CREATED 

I FREED 

I EXPLICITLY BY DELETING THE CONTAINING SEGMENT 
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. ™1 AREA. LINKER .SEGMENT ' 
GE'TTING SPACE FOR PROGRAM VARIABLE; 



a CONTROLLED STORAGE - INTERNAL 



I EXPLICITLY-ALLOCATED DATA, KNOWN TO ONE PROGRAM 



1 ux:<v«i^An.A i. xuLM 



I PL/1: del c controlled int; /* int is default */ 
allocate c; 
allocate c; 



I LOCATION 

I ALLOCATED IN USER FREE "AREA IN [unique] .area .linker 

I ALLOCATED ANE INITIALIZED 

I EXPLICITLY 3Y PL/1 allocate STATEMENT 

I FREED 

I EXPLICITLY 3Y PL/1 free STATEMENT ' 
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^ THE AREA. LINKER SEGMENT 
GETTING SPACE FOR PROGRAM VARIABLES 

a CONTROLLED STORAGE - EXTERNAL 

I EXPLICITLY-ALLOCATED DATA, SHARED BETWEEN PROGRAMS 

I DECLARATION 

I PL/1: declare ce controlled external; 
allocate ce; 

I LOCATION 

I ALLOCATED IN USER FREE AREA IN [unique] . area . 1 inker 

I ALLOCATED AND INITIALIZED 

I EXPLICITLY 3Y PL/1 allocate STATEMENT 

I FREED 

I EXPLICITLY BY PL/1 free STATEMENT 
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'^^S AREA.. LINKER SEGMENT 

■ GETTING SPACE FOR PROGRAM VARIABLES 

BASED - IN AN AREA 

I EXPLICITLY-ALLOCATED DATA, KNOWN ONLY TO ONE PROGRAM, QUALIFIED 
BY A LOCATOR 

I DECLARATION 

I PL/1: del area area, 

b based (p) , 
P Ptr ; 
allocata b in (area); 

I LOCATION 

I "DEPENDS WHERE THE USER 'SPECIFIES THE AREA TO' BE {PERHAPS THE 
SYSTEM FREE AREA SUPPLIED BY INVOKING get_sy3tem_£ree_area_) 

I ALLOCATED AND INITIALIZED 

I EXPLICITLY BY PL/1 allocate STATEMENT 

I FREED 

I EXPLICITLY BY PL/1 free STATEMENT 
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THE AREA. LINKER SEGMENT 
GETTING SPACE FOR PROGRAM VARIABLES 

a BASED - NO AREA 

I EXPLICITLY-ALLOCATED DATA, KNOWN ONLY TO ONE PROGRAM, QUALIFIED 
BY A POINTER 

I DECLARATION 

I PL/1: declare b based(p), 

(p,pl) ptr; 
allocate b; 
allocate b set(pl); 

I LOCATION . . , ._. , . 

I IN USSR FREE AREA WITHIN [ unique] .area . 1 inker 

I ALLOCATED AND INITIALIZED 

I EXPLICITLY BY PL/1 allocate STATEMENT 

I FREED 

I EXPLICITLY BY PL/1 free STATEMENT 
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THE AREA. LINKER SEGMENT 
GETTING SPACE FOR PROGRAM VARIABLES 

BASED - IN AN I/O BUFFER 

I EXPLICITLY-ALLOCATED DATA, KNOWN ONLY TO ONE PROGRAM, QUALIFIED 
BY A POINTER 

I DECLARATION 

I PL/1: declare b based(p), f file; 

read file(f) set(p); 
locate b file{f) 3et{p); 

I LOCATION 

I IN. .P^N- I/O BUFFER. .ALLOCATED BY. , PL/1 IN ..USER FREE AREA. .IN 
[unique']-, area, linker ' • ■ 

I ALLOCATED 

I EXPLICITLY BY PL/1 read (WITH set OPTION) OR locate STATEMENT 

I INITIALIZED 

I BY locate STATEMENT 

I FREED 

I BY SUBSEQUENT I/O OPERATION ON THE FILE 
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THE AREA. LINKER SEGMENT 



GETTING SPACE FOR PROGRAM VARIABLES 



a COBOL DATA 



I INTERNAL STATIC-LIKE DATA, KNOWN ONLY TO ONE PROGRAM 



I DECLARE 



I COBOL: WORKING SECTION. 

77 CB PIC IS 99. 



I LOCATION 

I ALLOCATED IN USER FREE AREA 

I ALLOCATED AND INITIALIZED 

I WHEN THE PROGRAM IS FIRST CALLED 

I FREED 



I WHEN THE PROCESS OR COBOL RUN UNIT TERMINATES, OR EXPLICITLY 
(BY A cancel_cobol_program COMMAND OR A CANCEL STATEMENT) 
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TOPIC VI 
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Topic VI MULTICS DYNAMIC LINKING Topic VI 

OBJECTIVES: 

Upon completion of this topicr students should be able to! 

1. Compare conventional linking with Multics dynamic iinkins. 

2. List the functions performed by the Multics dynamic linker 

3. Trace the operation of the dynamic linker from the time it 
first encounters an unsnapped link until it resolved the 
linkase fault. 

4. Discuss the side-effects of dynamic linking and some of the 
dansers related to it. 



5, Explain wha.t happens when binding occurs and why it can be 
used to. great, advantase,. 



Multics 
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INTRODUCTION 



LINKING 



I A LINKER IS BASICALLY A POST COMPILER 



I SYMBOLIC REFERENCES TO LOCATIONS NOT WITHIN THE OBJECT NORMALLY 
CAUSE THE TRANSLATOR TO PRINT AN ERROR MESSAGE 



I TELLING THE COMPILER OR ASSEMBLER THAT A SYMBOL IS EXTERNAL IS 
JUST A FUDGE SO THAT IT WON'T COMPLAIN 



I THE TRANSLATOR STILL CAN'T CALCULATE AN ADDRESS, SO IT BUILDS A 
STRUCTURE TELLING WHAT IT WAS LOOKING FOR 



I'- /IT • I S ■ ■ THE ■ JOB • 'OP THE LINKER TO * ""RESOtlVE ALL^ ' " TliE-S'E UNLINKE D 
REFERENCES ■ " * • * " ' 



t To Be Reproduced 



6-1 



F21 



INTRODUCTION 
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INTRODUCTION 

THE TRADITIONAL LINKER 

I PHILOSOPHY 

I LINKING MUST BE DONE BEFORE THE PROGRAM RUNS 

I LINKING IS ASSOCIATED WITH LOADING - PLACING THE PROGRAM IN 
MEMORY 

I ALL EXTERNAL REFERENCES MUST BE PRESENT AT LINKING TIME 

I THE LINKER PRODUCES A "LOAD UNIT" OR "BOUND UNIT" - ABLE TO 
BE PLACED IN MAIN MEMORY WITH ALL ADDRESSES RESOLVED 

I THE LOAD UNIT IS THEN RUN BY THE USER 
I LIMITATIONS 

I THE LINKER IS THE LAST STEP IN ADDRESS RESOLUTION - IF IT 
CAN'T DO IT, NOTHING CAN 

I BECAUSE TRADITIONAL LINKING IS ASSOCIATED WITH REAL MEMORY, 
ALL PROGRAMS HAVE TO BE PRESENT TO GET A SPOT IN THE BOUND 
UNIT, AND HENCE THE MEMORY 

I IF THE LINKER CAN'T RESOLVE A LINK, THE LINKING FAILS 

I CHANGING ONE PROGRAM IMPLIES LINKING EVERYTHING OVER AGAIN 

I SUBSTITUTING A PROGRAM MID-EXECUTION IS IMPOSSIBLE 
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INTRODUCTION 
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INTRODUCTION 



B THE DYNAMIC LINKER 



I PHILOSOPHY 

I IN AN OPERATING SYSTEM WITH MANY (100 PLUS) SEGMENTS, LOADING 
AND RELOCATION BECOME PART OF THE JOB OF THE HARDWARE, NOT 
THE SOFTWARE 

I RESOLVING REFERENCES BECOMES EASIER BECAUSE THE TRANSLATOR 
GENERATES ADDRESSES RELATIVE TO THE BASE OF THE PROGRAM, AND 
HENCE THE SEGMENT 

I THE JOB OF THE LINKER HAS BEEN REDUCED TO FINDING A SEGMENT 
NUMBER AND AN OFFSET WITHIN THE SEGMENT TO COMPLETE THE 
EXTERNAL REFERENCE 

■ T ' With" RELOCXfl at 'ALREADY' TAKEN CA'RE" "OF,' AND "LINKING' REDUCED TO'' 
'■ THE "CALCULATION OF TWO" NUMBERS, LINKING CAN BE POSTPONED 
UNTIL THE' EXTERNAL REFEENCE IS MADE 

I ALTHOUGH DYNAMIC LINKING IS POSSIBLE USING A REAL MEMORY, 
UNSEGMENTED MACHINE, THE BY-PRODUCTS OF SEGMENTATION MAKE IT 
WORTH WHILE TO IMPLEMENT 

I WITH THE DRUDGERY OF PRE-L INKING TAKEN AWAY FROM THE 
PROGRAMMER, S/HE CAN SPEND MORE TIME WORRYING ABOUT THE 
PROGRAM, AND NOT ABOUT THE MEMORY MANAGEMENT 



I LIMITATIONS 

I EXCESSIVE USE OF DYNAMIC LINKING CAN SLOW THE OVERALL SYSTEM 
THROUGHPUT 

I BY GIVING THE JOB OF LINKING TO THE OPERATING SYSTEM, THE 
PROGRAMMER HAS LESS SAY OVER WHICH VERSION OF A PROGRAM IS TO 
BE USED 
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INTRODUCTION 



I ADVANTAGES 



I PROGRAMS ARE EXECUTEABLE WITHOUT ALL EXTERNAL REFERENCES 
BEING PRESENT - ONE NEED ONLY WRITS AND DEBUG A SMALL PORTION 
AT A TIME 



I SUBSTITUTING SUBROUTINES CAN BE DONE AT RUNTIME WITH LITTLE 
EFFORT AND COST TO THE OPERATING SYSTEM 



I EXTERNAL REFERENCES THAT ARE AVOIDED BECAUSE OF TRANSFERS 
WITHIN A PROGRAM NEVER HAVE TO BE RESOLVED 
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INTRODUCTION 
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MULTICS COMPILER CONVENTIONS 



a EXTERNAL REFERENCES 

I ALL STANDARD MULTICS COMPILERS GENERATE THE SAME TYPE OF LINK 
THAT RELATES TO BOTH PRELINKING (BINDING) AND DYNAMIC LINKING 

I IS A REPOSITORY FOR THE EXTERNAL ADDRESS 

I CONTAINS INFORMATION TELLING ABOUT THE NAME OF THE EXTERNAL 
REFERENCE, INTERNAL LOCATIONS, WHETHER OR NOT TO CREATE IT IF 
NOT FOUND, ETC. 

a THE LINK 

. I INITIALLY CREATED IN THE LINKAGE SECTION OF THE OBJECT SEGMENT 
I ONE FOR EACH EXTERNAL REFSRE'ICS 

I IS TWO WORDS LONG 

I MAY BE UNSNAPPED 

I THE END OF THE FIRST WORD CONTAINS THE " FAULT -TRAP 2" CODE 

I THE REST OF THE LINK CONTAINS ADDRESSES OF INFORMATION FOR 
THE LINKERS 

I MAY BE SNAPPED 

I THE END OF THE FIRST WORD CONTAINS THE "ITS" CODS - 
INDICATES A VALID MULTICS POINTER 
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jyiULTICS COMPILER GONVRNTIONS 



I THE FIRST HALF OF THE FIRST WORD CONTAINS THE SEGMENT 
NUMBER OF THE EXTERNAL REFERENCE 

I THE FIRST HALF OF THE SECOND WORD CONTAINS THE OFFSET 
WITHIN THE SEGMENT OF THE EXTERNAL REFERENCE 



THE LINKAGE SECTION 



I CONTAINS ALL THE LINKS A PROGRAM NEEDS 



I IS COPIED OUT OF THE OBJECT SEGMENT BEFORE THE OBJECT IS 
EXECUTED 



I IS MERGED INTO THE COMBINED LINKAGE • AREA ■ 
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MULTICS COMPILER CONVENTIONS 



000000 


DEFS 


TRAP 


POINTER TO SYMBOL SECTION 


POINT 


ER TO L 


INKS' 


ORIGIN 


UNUSED 




LENGTH 


SEGNO 


LENGTH 



LINK 



LINK 
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MUTLICS XDeERATXNG . SYSTEM SUFP.ORT. 



a MANAGEMENT OF EXTERNAL REFERENCES 



I WITH FEW EXCEPTIONS, COMPUTERS EXPECT ADDRESSES TO BE IN NUMERIC 
(BINARY) FORM 



I THE MULTICS HARDWARE CURRENTLY FOLLOWS THIS ARCHITECTURE 



I THE DESIGNERS OF MULTICS DECIDED THAT IT WAS TIME TO MOVE AWAY 
FROM SOFTWARE ALSO USING NUMBERS 



I PROGRAMMERS STOPPED PROGRAMMING IN BINARY MACHINE LANGUAGE 
YEARS AGO, USING A MNEMONIC ASSEMBLY LANGUAGE 

.1 - HUMANS, REMEMBER, AND MANIPULATE WORDS MORE EFFICIENTLY. .THAN 



THE HARDWARE LOCATIONS OF DATA MAY CHANGE, BUT THE NAME WILL 
REMAIN THE SAME 



I SOFTWARE TECHNOLOGY NOW ALLOWS SYMBOLIC NAMES TO BE 
AUTOMATICALLY MANAGED CHEAPLY 



I MULTICS SUPPORTS SYMBOLIC (VIRTUAL) ADDRESSES FOR POTENTIALLY 
ALL THE DATA ON THE SYSTEM 



I SPECIFIED BY A TWO COMPONENT NAME IN THE FORM OF 
alpha$beta 

I alpha IDENTIFIES A SEGMENT 

I beta IDENTIFIES A LOCATION WITHIN THE SEGMENT 
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MUTLICS OPERATING SYSTEM SUPPORT 



I MULTICS WORRIES ABOUT THE HARDWARE NUMBER ASSOCIATED WITH 
alpha 

I MULTICS WORRIES ABOUT THE HARDWARE NUMBER ASSOCIATED WITH 
beta 

I THE PROGRAMMER IS CONCERNED ONLY WITH REMEMBERING AND 
MANAGING THE ENTITY alpha$beta 

I THIS SCHEME IS IMPLEMENTED EVEN AT THE MULTICS ASSEMBLY 
LANGUAGE LEVEL 

I MULTICS MANAGES SEVERAL TABLES TO MAINTAIN THE ASSOCIATION 
BETWEEN A SYMBOLIC NAME AND ITS HARDWARE NUMBERS 

.1 , dseg....... 

I kst 

I RNT 

I DEFINITION SECTION IN OBJECT SEGMENTS 

I THERE IS AN INTERPLAY AMONG THE TABLES 

I dseg AND kst CAN BE CONSIDERED AS A NECESSARY PAIR 
I dseg TELLS THE HARDWARE WHERE SEGMENTS ARE 

I kst TELLS THE SOFTWARE WHO SEGMENTS ARE 

I THE RNT LISTS ALIASES FOR SEGMENTS LISTED IN THE kst 
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THE LINKER . - PHASE I 



THE FAULT 



I PROLOGUE 



I THE INSTANT A PROGRAM BEGINS TO RUN, IT HAS NOT YET MADE ANY 
CALLS 



I ITS LINKAGE SECTION WILL CONTAIN ONLY UNSNAPPED LINKS BECAUSE 
LINKS ARE NOT SNAPPED UNTIL NEEDED 



I AN ATTEMPT TO REFERENCE THROUGH ANY OF THESE LINKS WILL CAUSE 
A HARDWARE FAULT 
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■ THE LIHKSR - PHASE I 
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PR4 
PR5 

PR6 
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LINK 


LINK 
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THE.- LINKER PHASE T 



I THE FAULT HANDLER 



I A REFERENCE THROUGH A LINK IS DONE WITH HARDWARE INDIRECTION 

I ALL THE LINK DOES IS TELL THE HARDWARE WHERE TO GO FOR THE 
NEXT REFERENCE 

I USES AN ITS-PAIR 



I IF THE HARDWARE FINDS THE BIT PATTERN 100110 AT THE END OF 
THE FIRST WORD OF A LINK, IT FALLS INTO A FAULT TRAP 2. 

I THE WHOLE PROCESSING UNIT IS HALTED AND THE MACHINE IS FORCED 
. TO EXECUTE THE PROGRAM fim ^^^^^ x.-^,,c.PT Xv^oW 

I FROM THIS POINT ON, CONTROL IS IN THE HANDS OF THE 
. SUPERVISOR 

I THIS IS RING ZERO * 

I THERE IS NO WAY FOR THE USSR TO INTERCEPT THIS FAULT 

I fim ASCERTAINS THAT THE FAULT WAS FAULT TRAP 2 AND CALLS THE 
PROGRAM link_snap___ 

I link_snap_IS THE DYNAMIC LINKER 
I " ink_snap FIRST VERIFYS THAT THIS IS A VALID UNSNAPPED LINK 
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THE. LINKER - PHASE I 



?R4 
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THE LIl^KSR - PHASE. "I 



,8 SEARCH FOR THE NAME 



I link_snap LOOKS AT THE LINK THAT CAUSED THE FAULT AND EXTRACTS 
FROM IT POINTERS BACK TO THE OBJECT SEGMENT 



I IN THE OBJECT, AS PART OF THE DEFINITION SECTION, ARE 
"OUTWARD-REFERSNCING-SYMBOLS" THAT NAME THE SEGMENT AND LOCATION 
WITHIN IT THAT WE WANT 



I link_snap OBTAINS THE TWO SYMBOLIC NAMES THAT MAKE UP THE 
VIRTUAL ENTRY DESCRIBING THE FAULTED LINK FROM THIS LIST OF 
SYMBOLS 
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THE LINKER - PHASE I 
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THE- LINKER -PHASE II 



OBTAINING THE SEGMENT NUMBER 



I A SEGMENT NUMBER DESCRIBES TO HARDWARE THE LOCATION OF A REAL 
SEGMENT; THE DYNAMIC LINKER HAS TO FIND THAT REAL SEGMENT 



I THE SEARCH RULES 



I EACH PROCESS HAS A LIST OF PLACES TO SEARCH JUST IN CASE 
LINKAGE FAULTS OCCUR (WHICH IS INEVITABLE) 



I THIS IS THE USER MODIFIABLE ATTRIBUTE OF A PROCESS CALLED 
"THE SEARCH RULES" 



I A SPECIAL CASE: initiated segments 

■■ • I ■ ■ THE LINRER- GOES- T0-'THE 'Rt4T'' 

■ I IT ■ LOOKS" UP THE NAME OF- THE SEGMENT ■ IT' OBTAINED DURING 
PHASE I (THE RNT IS A BUNCH OF LINKED LISTS) 

I IF THE NAME IS FOUND, THEN THE NUMBER ASSOCIATED WITH IT 
IS ASSUMED TO BE THE DESIRED SEGMENT NUMBER 

I IF THE NAME WAS NOT FOUND, THEN WE MOVE ON TO THE NEXT 
SEARCH RULE 
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THE LINKER - PHASE II 
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THE LINKER - PHASE II 

I A HUNCH: rsf arenc ing_dir 

I THE SECOND RULE IN THE SEARCH RULES IS ref erenc ing_dir 

I THIS MEANS THE LINKER WILL LOOK IN THE DIRECTORY OF THE 
PROGRAM THAT CAUSED THE LINKAGE FAULT FOR THE SEGMENT 

I ALTHOUGH THIS IS NOTHING MORS THAN THE LIST COMMAND, IT IS 

NOT AN INEXPENSIVE OPERATION 

I ITS PURPOSE IS TO CONTAIN THE GLOBAL NATURE OF THE DYNAMIC 
LINKER IN ITS SEARCH FOR THE SEGMENT 

I THIS TENDS TO ISOLATE ALL THE PROGRAMS IN A DIRECTORY INTO 
A SUBSYSTEM 

I THE DANGER OF THIS WILL BE STATED LATER 



Not To Be Reproduced 



6-21 



F21 



THE LINKER - PHASE II 
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THE LINKER - PHASE II 



I THE LINKER FIGURES THAT THE USER HAS THE PROGRAM AND WILL 
LIST THE CONTENTS OF THE WORKING DIRECTORY 

I THIS ALSO TENDS TO CONTAIN THE WORKING DIRECTORY INTO A 
SUBSYSTEM OF SORTS 

I IT ALSO LETS THE USER ACCUMULATE A LIBRARY OF INTERWOVEN 
PROGRAMS 
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THE LINKER - PHASE 11 
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THE LINKER .".. PHASE II 



I SYbTtiM LiBKAKlJiS 



I HERE BEGINS THE BIG SEARCH 

I AGAIN, A LIST FOR EACH DIRECTORY UNTIL THE LINKER FINDS 
THE SEGMENT IN QUESTION 

I THIS CAN EASILY BECOME THE MOST TIME CONSUMING JOB OF THE 
DYNAMIC LINKER 



I IF THE SEGMENT WAS NOT FOUND IN EITHER THE RNT OR THE 
DIRECTORIES, THEN THE "linkage error" CONDITION IS SIGNALLED 



I IF THE SEGMENT" WAS NOT FOUND ' IN THE RNT, BUT WAS FOUND IN A 
DIRECTORY, ADD IT TO THE kst AND RNT 

..... I-v. IF-.NOJ. .. :IN .THSl kstr. ^TEENTHE PROGRAM-.. .IS NOT- XN- .THE , ADDRESS 
SPACE OF THE PROCESS AND CAN'T" BE USED - ' " 



I AFTER ADDING THE PROGRAM INTO THE kst "THE LINKER ALSO PLACES 
THE SEGMENT NAME INTO THE RNT 



I THE SEGMENT NAME WE OBTAINED IN PHASE ONE IS NOW A REFERENCE 
NAME 



I SUBSEQUENT SEARCHES FOR THIS NAME BY FUTURE PROGRAMS IS THIS 
PROCESS WILL FIND A MATCH IN THE RNT, AND HAVE AN INEXPENSIVE 
LINKAGE FAULT 
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THE LINKER - PHASE II 
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THE - LINKER. - 

s OBTAINING THE OFFSET VALUE 

I LOCATE THE DEFINITION SECTION OF 
I OBTAIN THE BIT COUNT FROM THE 

I DIVIDE IT BY 36 
I SUBTRACT 1 

I THIS IS THE LOCATION OF THE 
LOCATE THE OBJECT MAP 

I WITHIN THE OBJECT MAP FIND 
SECTION 



PHASE II 

THE JUST FOUND SEGMENT 
DIRECTORY 

OBJECT MAP POINTER; USE IT TO 
THE ADDRESS OF THE DEFINITION 
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THE LINKER - PHASE II 



(This' page intentionally left blank) 
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THE LINKER - PHASE 11^ 

I WALK THROUGH THE DEFINITION SECTION 
I THIS IS ANOTHER LINKED LIST 

I LOOK FOR A CHARACTER ON THE CHAIN THAT MATCHES THE SECOND 
NAME EXTRACTED FROM PHASE ONE. 

I ASSOCIATED WITH THIS NAME IS A BINARY OFFSET THAT THE 
HARDWARE CAN USE 

I THE LINKER NOW HAS ALL THE INFORMATION NECESSARY TO SNAP THE 

LINK 



SNAPPING THE LINK 



I BACK IN THE FAULTING OBJECT SEGMENT WAS AN UNSNAPPED LINK 



I THE LINKER WILL OVERWRITE THIS INFORMATION WITH THE NEWLY FOUND 
SEGMENT NUMBER AND OFFSET 



I THE LINKER WILL PLACE BINARY 100011 IN THE LAST SIX BITS OF THE 
FIRST WORD OF THE LINK 



I THE LINK IS NOW A STANDARD POINTER - IT IS SNAPPED 



I ANY FURTHER REFERENCES THROUGH THIS LINK WILL NOT RESULT IN A 
FAULT 
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THE LINKER - PHASE II 



THIS SNAPPING DOES NOT EFFECT ANY OTHER LINK WITHIN THE LINKAGE 
SECTION 
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THE LINKER - PHASE II 



UNSNAPPED LINK 



ADDRl 



46 



ADDR2 



SNAPPED LINK 



410 




43 \ 


, 1 

56U j 
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THE LINKER ^ PHASE II 



a LOADING THE OBJECT SECTIONS 



I THE NEWLY REFERENCED SSGxMENT MAY HAVE A LINKAGE AND STATIC 
SECTION OF ITS OWN THAT MUST BE LOADED INTO MEMORYY 



I THE DYNAMIC LINKER PERFORMS THE COPYING OF THE STATIC AND 
LINKAGE TEMPLATES INTO THE PROPER AREAS 



I IF THE LOT WORD CORRESPONDING TO THE SEGMENT IS EMPTY (I.E. LOT 
(SEGMENT NUMBER) =0) THEN THE LINKER WILL COPY IT 



I GET SOME ROOM IN THE COMBINED LINKAGE AREA FOR THE LINKAGE 
SECTION 



I COPY THE LINKAGE TEMPLATE FROM THE OBJECT INTO THE SPOT IN 

THE COMBINED LINKAGE AREA 



I PLACE THE ADDRESS OF THE LINKAGE SECTION INTO THE LOT ENTRY 



I • PERFORM THE SAMS WITH THE STATIC SECTION, USING THE ISOT AND 
COMBINED STATIC AREA 



I NOTE: THE STATIC MAY BE COMBINED WITH THE LINKAGE 
INFORMATION, IN WHICH CASE THE STATIC WAS LOADED WITH THE 
LINKAGE SECTION 
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THE LINKER - PHASE II 



OBJECT SEGMESrr 



TEXT 



DEFS 



LINKAGE 
TEMPLATE 



INTERNAL 

STATIC 
TEMPLATE 



SYMBOLS 



OBJECT 
MAP 



BREAK MAP 
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COMBINED LINKAGE AREA 



LINKAGE 
SECTION 



COMBINED STATIC AREA 



INTERNAL 
STATIC 
SECTION 



LINKAGE 
OFFSET TABLE 
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INTERNAL STATIC 
OFFSET TABLE 
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THE LINKER - PHASE II_ 

a INSTRUCTION RETRY 

I RETURN TO THE SCENE OF THE CRIME 

I WHEN link_snap IS FINISHED, IT RETURNS TO fim 

I fim THEN CAUSES THE INSTRUCTION THAT GENERATED THE LINKAGE 
FAULT TO 3E REEXECUTED 

I WITH THE LINK NOW SNAPPED, A FAULT WILL NOT OCCUR AND THE 
INSTRUCTION WILL FIND THE THING IT WAS LOOKING FOR 
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THE LINKER - PHASE II 



(This page intentionally left blank) 
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BY-PRODUCTS OF DYNAMIC LINKING 



s INITIATION 



I EVERY SEGMENT THAT A PROCESS WANTS TO USE MUST BE REGISTERED 
WITH BOTH THE dseg AND kst 

I IF A SEGMENT IS NOT REGISTERED - KNOWN - TO A PROCESS AND IT IS 
THE OBJECT OF A LINKAGE FAULT, THEN THE DYNAMIC LINKER WILL MAKE 
IT KNOWN 

I THIS INVOLVES GOING TO THE kst, FINDING OUT THE NEXT FREE 
NUMBER TO USE AND ASSIGNING IT TO THE NEW SEGMENT 

I BECAUSE THIS IS PRETTY MUCH AN UNPREDICTABLE OPERATION AS FAR 
AS AVAILABLE NUMBERS ARE CONCERNED, MULTICS DOSS NOT 
GUARANTEE THE CONSISTENCY OF SEGMENT NUMBERS ACROSS PROCESS 

BOUNDARIES 



a HIDDEN DANGERS 



I THE SEARCH FOR A SEGMENT TO FULFILL THE LINKAGE FAULT CAN CREATE 
DANGERS FOR PROGRAMMERS WHO ARE NOT AWARE OF THE NATURE OF THE 
SEARCH 



I CONSIDER THE FOLLOWING SCENARIO 

I A PROGRAMMER HAS WRITTEN A SET OF PROGRAMS 
THE FIRST PROGRAM IS CALLED driver 
IT CALLS calculate^total 

IT THEN CALLS ioa_ TO PRINT THE TOTAL OUT 

LATER (AND ALTHOUGH UNLIKELY, POSSIBLE) driver CALLS A 
PROGRAMMER PROVIDS.D PROGRAM NAMED formline 
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BY-PRODUCTS OF DYNAMIC LINKING 



I THERE IS A SIGNIFICANT CHANCE THAT THE PROGRAMMER SUPPLIED 
formline WILL NOT EXECUTE 



I THE MULTICS SYSTEM SUBROUTINE, ioa_, ALSO CALLS A PROGRAM 
NAMED formline_ 

IF ioa_ TOOK A LINKAGE FAULT WHILE CALLING formlins , IT 
WOULD HAVE FOUND THE SYSTEM'S COPY USING THE refer enc ing_d ir 
RULE, PLACED S NAME IN THE RNT, AND driver WOULD HAVE FOUND 
IT WHEN IT CALLED formline . 



I NOTE, THEN THAT IT IS POTENTIALLY DANGEROUS TO CALL PROGRAMS 
OUTSIDE THE DIRECTORY OF EXECUTION IF THE NAMES OF SEGMENTS CAN 
BE DUPLICATED ELSEWHERE 



I BINDING ALSO HELPS 



BINDING 



I BINDING ITSELF IS A LINKING PROCESS, BUT ITS EFFECTS CAN 3S FELT 
SYSTEM WIDE 



I THIS EXPLANATION WILL CONCERN ITSELF WITH ONLY THE' LINKING 
ASPECTS OF BINDING 



I ONE OF THE ADVANTAGES OF DYNAMIC LINKING IS THAT UNUSED EXTERNAL 
REFERENCES WERE NOT LINKED, SAVING TIME 



I IF A SET OF PROGRAMS MAKE MANY CALLS TO EACH OTHER AND IT IS 
ALMOST UNAVOIDABLE THAT ALL LINKS WILL BE SNAPPED IN THE COURSE 
OF THEIR EXECUTION, THEN PRELINKING WILL BE CHEAPER 
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BY-PRODUCTS OF DYNAMIC LINKING 



I EACH LINK WILL BE SNAPPED ONCE IN ITS LIFE, AS OPPOSED TO 
mm TIMES WITH DYNAMIC LINKING 



I THE PROGRAMMER MUST GIVE UP THE ABILITY TO MAKE CHANGES TO 
OBJECT EASILY; THEREFORE BINDING SHOULD BE DONE ONLY AFTER 
THE PROGRAMS ARE FULLY DEBUGGED 



I THE BINDER'S TASK 

I BREAK APART ALL THE SECTIONS OF ALL THE PROGRAMS TO BE BOUND 
I GROUP ALL LIKE SECTIONS TOGETHER (TEXT WITH TEXT, ETC) 



I COMBINE ALL THE LINKAGE SECTIONS TOGETHER, AND ELIMINATE ALL 
LINK DUPLICATIONS 



I ELIMINATE SOME SNTRYPOINTS INTO THE PROGRAMS, TRIMMING DOWN 
THE DEFINITION SECTION 



I GENERATE ONE OBJECT MAP AND OBJECT MAP POINTER 



I A BOUND SEGMENT MAY ACTUALLY HAVE LINKS LEFT OVER THAT WERE NOT 
RESOLVED AT BINDING TIME; THEY WILL BE HANDLED 3Y THE DYNAMIC 
LINKER WHEN NEEDED 
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TOPIC VII 



The Multics Programming Environment 7-1 

Destruction of the Programming Environment. , 7-1 

Error Recovery Techniques 7-8 

The Multics Programming Environment 7-1 

Destruction of the Programming Environment, . 7-1 

Error Recovery Techniques 7-8 
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Topic VII MULTICS PROGRAMMING ENVIRONMENT Topic VII 

objectives: 

Upon completion of this topicr students should be able to: 



1. Discuss some of the ways in which the Multics process 
environment can be disrupted. 



1 n/>atia ^ nM n w ir a f ^ ttaaw a »• n a a tr.tn i n a atripnire i . i K -i ^ K «>aitcei a 

process to terminate abnormally. 

3. Apply preventive techni'iues during program development to 
minimize the number of potentially dangerous programming 
errors. 



Multics VII-1 FE1 



uESTRUCtlON OF THE PROGRAMMING ENVIRONMENT 

I SOURCE SEGMENT 

I WHEN INITIATED BY THE COMPILER, NOT GIVEN A REFERENCE NAME 
I USUALLY NOT MADE KNOWN EXCEPT BY COMPILER 

I SEGMENT USUALLY NOT KNOWN 

I DESTRUCTION UNLIKELY 

I OBJECT SEGMENT 

I SEGMENT READ-EXECUTE ONLY (EXCEPT WHEN DEBUGGER IS SETTING 
BREAKPOINTS) 

I DESTRUCTION UNLIKELY BECAUSE OF HARDWARE PROTECTION 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 

stack^n SEGMENT 

I IN [pd] 

I READ-WRITE 

I INCLUDES 

I PROGRAM ACTIVATION HISTORY (STACK) 

I AUTOMATIC VARIABLES 

I STACK HEADER INFORMATION 

I INCLUDES INITIAL LOT & ISOT ALLOCATIONS 

I DESTRUCTION POSSIBLE THROUGH MISUSE OF AUTOMATIC VARIABLES OR 
BUILT-IN FUNCTIONS 

I SUBSCRIPTRANGE 

I STRINGRANGE 

I USE OF UNINITIALIZED POINTER TO BASED VARIABLE 
I SYMPTOMS 

I IF STACK HEADER OVERWRITTEN, FATAL PROCESS ERROR USUALLY 
OCCURS 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 



I STRINGRANGE OFTEN RESULTS IN STORAGE CONDITION (out_of_bounds 
ON USER'S STACK) 



I SUBSCRIPTRANGE CAUSES AUTOMATIC DATA AND/OR PROGRAM 
ACTIVATION INFORMATION TO BE OVERWRITTEN, LEADING TO IMPROPER 
RESULTS AND PROGRAM OPERATION 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 



s [ unique] .area .1 inker SEGMENT 
I IN [pd] 
I READ-WRITE AREA 

I INCLUDES 

I COMBINED LINKAGE AREA 

I LINKAGE SECTIONS 
I LOT 
I I SOT 
I • RNT 

I COMBINED STATIC AREA 

I INTERNAL STATIC SECTIONS (VARIABLES) 

I USSR FREE AREA 

I EXTERNAL STATIC AND COMMON VARIABLES - PER PROCESS 
I EXTERNAL VARIABLE CONTROL INFORMATION 
I CONTROLLED VARIABLES 

I BASED VARIABLES - NO AREA, IN AN I/O BUFFER 
I COBOL VARIABLES 

I ASSIGNED LINKAGE AREA 

I BASED STORAGE-ALLOCATED THROUGH hcs_$assign_linkage 
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DESTRUCTION OF THE PROGRAiMMIMG ENVIRONMENT 

a [ unique] .area. 1 inker SEGMENT (continued) 

I DESTRUCTION POSSIBLE THROUGH 
I SUBSCRIPTRANGE 
I STRINGRANGE 

I USE OF UNINITIALIZED POINTERS 

I MISUSE OF AREA 

I -gj^g&TNG ^AMs!. gA&SB. VARIABLE TWICE - 

I SYMPTOMS 

I IF LINKAGE SECTIONS OVERWRITTEN, IMPROPER PROGRAM OPERATION 



I IF LOT OVERWRITTEN, IMPROPER OPERATION OF ALL PROGRAMS 



I IF I SOT OVERWRITTEN, IMPROPER INTERNAL STATIC DATA; 
SUBSEQUENT DESTRUCTION OF OTHER DATA 



I IF RNT OVERWRITTEN, UNABLE TO FIND PREVIOUSLY-REFERENCED 
PROGRAMS 



I IF VARIABLES (OF ANY STORAGE CLASS) ARE OVERWRITTEN, IMPROPER 
VARIABLE VALUES 



I IF EXTERNAL VARIABLE CONTROL INFORMATION OVERWRITTEN, 
IMPROPER COMMUNICATION OF SHARED VARIABLES BETWEEN PROGRAMS; 
IMPROPER DATA VALUES 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 

I IF AREA CONTROL INFORMATION OVERWRITTEN, bad_area_f orma t 
CONDITION 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 



DIRECTORIES, dseg, kst 



I NO DIRECT ACCESS TO USER FROM USER RING {RING 4) 



I DESTRUCTION UNLIKELY, SEGMENTS PROTECTED 3Y HARDWARE 
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ERROR RECOVERY TECHNIQUES 



I ARE CAUSED BY IMPROPER SUBSCRIPTS, BAD SUBSTRING OPERANDS, OR 
POINTERS USED IMPROPERLY 



I RECOVERY FROM SUBSCRIPTRANGE AND STRINGRANGE 



I RECOMPILE PROGRAMS CAUSING THESE ERRORS AND ENABLE CHECKING 
FOR THESE CONDITIONS 



I PL/1: INSERT A LINE CONTAINING 



^ { si ze ^ ^^^st^ing si ze , str^ ngrange, subscriptrange) : 

AT THE BEGINNING OF EACH SOURCE SEGMENT, AND RECOMPILE 
WITH -table OPTION 

I COBOL: USE -run time_check AND -table CONTROL ARGUMENTS IN 
cobol COMMAND 

I FORTRAN: USE -subscriptrange AND -table CONTROL ARGUMENTS 
IN fortran COMMAND 



I RUN PROGRAMS 

I IF CONDITIONS ARE SIGNALLED, USE probe TO FIND CAUSE 

I FIX PROBLEMS, AND RECOMPILE AS ABOVE UNTIL NO MORE CONDITIONS 
ARE SIGNALLED 



I IF NO MORE CONDITIONS ARE SIGNALLED, BUT PROGRAMMING 
ENVIRONMENT ERRORS STILL PERSIST 

I RECOMPILE WITHOUT THE CONDITION CHECKING, BUT WITH -table 
CONTROL ARGUMENT 

I PROCEED AS GIVEN BELOW UNDER "FURTHER ERROR RECOVERY" 
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ERROR RECOVERY TECHNIQUES 



I IF ALL ERRORS CORRECTED, RECOMPILE WITHOUT CONDITION CHECKING 
OR -table 



FURTHER ERROR RECOVERY 



I bad_area_format CONDITION IN [unique] .area. linker SEGMENT 



I CAUSED BY OVERWRITING AREA CONTROL INFORMATION 
I STORED AT BEGINNING OF AREA 
I STORED BETWEEN SPACE ALLOCATIONS 



I RECOVERY TECHNIQUES (ASSUMES STRINGRANGE AND SUB SCR I FT RANGE 
TESTS HAVE ALREADY BEEN DONE) 

I USE area_status COMMAND TO FIND FAULTY LOCATION IN AREA 

I USE dump__segment COMMAND TO PRINT AREA AROUND THAT 
LOCATION; RECOGNIZABLE DATA MAY LEAD TO THE CAUSE 

I USE create_area AND set_user_stor ag e COMMANDS TO SEPARATE 
USER FREE AREA FROM OTHER GROUPED AREAS 

I IF ERROR OCCURS NOW IN USER-SPECIFIED AREA SEGMENT, THEN 
PROBLEM IS IN A USER PROGRAM (NO SYSTEM PROGRAMS EXCEPT 
EXTERNAL VARIABLE MANAGER USE THIS AREA) 

I USE probe TO EXAMINE ALL POINTER-QUALIFIED REFERENCES TO 
BE SURE POINTER IS SET PROPERLY 

I AFTER SAgED-VARIAgI,g5 ^HAVE- — 8-EEN'''F"RlSDT~NU " Lr"THS ^^ 
TO ...ERi;V-SNT--StmSEQUENT"~REFERENCE TO FREED SPACE 
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ERROR RECOVERY TECHNIQUES 

s FURTHER ERROR RECOVERY (continued) 

I FATAL PROCESS ERRORS (REPRODUCIBLE) 

I CAUSED BY OVERWRITING 
I STACK HEADER . 

I LINKAGE OR INTERNAL STATIC SECTIONS OF CRITICAL PROGRAMS 
(iox__, listen_, command_^processor_^, pr int__ready__msg_, 
etc.) 

I RECOVERY TECHNIQUES 

I ATTEMPT TO ISOLATE POINT OF PROCESS FAILURE TO A SINGLE 
PROGRAM STATEMENT 

I USE probe TO 

I SET BREAKS AT KEY POINTS IN THE EXECUTION OF THE 
PROGRAM 

I CONTINUE EXECUTION AS EACH BREAK IS REACHED UNTIL FATAL 
ERROR OCCURS 

I WHEN FATAL ERROR OCCURS, POINT OF FAILURE LIES AFTER 
LAST BREAKPOINT WHICH WAS REACHED 

I SET BREAKS AFTER THIS POINT TO FURTHER ISOLATE POINT OF 
FAILURE TO A SINGLE STATEMENT 

I FAILING STATEMENT MAY BE 

I CAUSE OF ERROR 

I USING INCORRECT DATA AS RESULT OF A PREVIOUS ERROR 
I USE probe TO TRACK ORIGINAL CAUSE OF ERROR 

. I USE -watch CONTROL ARGUMENT OF trace COMMAND TO ISOLATE 
THE SUBROUTINE WHICH IS DAMAGING A PARTICULAR DATA ITEM 
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ERROR RECOVERY TECHNIQUES 



B FURTHER 'ERROR RECOVERY (continued) 



I FATAL PROCESS ERRORS (INTERMITTENT) 

I CAN BE CAUSED BY 

I UNINITIALIZED DATA VALUES 

I ANOTHER PROGRAM DESTROYING YOUR PROGRAM'S DATA 

I RECOVERY TECHNIQUES 

I IN A NEW PROCESS, RUN JUST THE FAILING PROGRAM 

I IF PROGRAM OPERATES CORRECTLY, ANOTHER PROGRAM MAY BE 
SOURCE OF ERROR 

I IF PROGRAM FAILS (ESPECIALLY FAILS INTERMITTENTLY OR IN 
DIFFERENT WAYS) , USE probe TO LOOK FOR UNINITIALIZED 
VARIABLES 
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TOPIC VIII 



Other Useful Debugging Tools 8-1 

list_^external_var iables 8-1 

list~external variables 8-1 

reset_externaT_^var iables 8-2 

reset"external~var iables 8-2 

delete^external^var iables 8-3 

delete external variables .•««..*»•» 8—3 

pr int__'5ind^raap."' 8-4 

pr int_bind~map 8-4 
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OTHER DEBUGGING COMMANDS 



Topic VIII 



OBJECTIVES! 

Upon completion of this topicr students should be able to: 

1. Manipulate external variables with the following commandss 

1 ist-.external_var iables <lev) 
reset-external. variables (rev) 
delete. external-variables (dev) 

2. Find and correct problems related to linkins with the 
following commands: 

pr i nt_bi nd-.map (pbm) 

print^link-inf 0 (pli) 

r esol ve-.l i nkase-er ror (rle) 

3. Use the trace-stack <ts) command in conjunction with trace 
and probe to determine the state of the process when an error 
occurs - 
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The 1 ist__external_var iables command prints information about 
variables managed by the system for the user, including FORTRAN common 
and PL/I external static variables whose names do not contain dollar 
signs. The default information is the location and size of each 
specified variable. 



Usage 

1 ist_external_var iables names { -control__args} 



where : 

1. names 

are names of external variables, separated by spaces. 

2. ' control_args 

can be chosen from the following: 

-unlabeled_common, -uc 

is the name for unlabeled (or blank) common. 

-long, -Ig 

prints how and when the variables were allocated, 
-all, -a 

prints information for each variable the system is 
manag ing . 

-no_header, -nhe 

suppresses the header. 
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Name: reset__external_var iables 

The reset_external_variables command reinitializes system-managed 
variables to the values they had when they were allocated. 

Usage 

reset_external_variables names { -control^arg} 



where : 

1. names 



are the names of the external variables, separated by 
spaces, to be reinitialized. 



2. control arg 

Ts - unlabel ed___common (or -uc) to indicate unlabeled (or 
block) common. 

Note 

A variable cannot be reset if the segment containing 
the initialization information is terminated after the 
variable is allocated. 
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Name: delete_external_var iables 

The delete external__var iables command deletes from the user's 
name space specTfied variables managed by the system for the user. 
All links to those variables are unsnapped and their storage is freed. 



Usage 

delete_external_var iables names {-control_arg} 



where: 

Ic names 

are the names of the external variables, separated by 
spaces, to be deleted. 

2. control arg 

Ts -unlabel ed_common (or -uc) to indicate unlabeled (or 
blank) common. 
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Name: pr int_bind_map 

The pr int_bind_map command displays all or part of the bind map 
of an object segment generated by version number 4 or subsequent 
versions of the binder. 

Usage 

pr int_bind_map path {components} { -control_args} 

where ; 

1. path 

is the pathname of a bound object segment. 

2. components 

are the optional names of one or more components of this 
bound object and/or the bindfile name. Only the lines 
corresponding to these components are displayed. A 
component name must contain one or more nonnumeric 
characters. If it is purely numerical, it is assumed to 
be an octal offset within the bound segment and the lines 
corresponding to the component residing at that offset are 
displayed. A numerical component name can be specified by 
preceding it with the -name control argument (see below). 
If no component names are specified, the entire bind map 
is displayed. 

3. control_args- 

may be chosen from the following list: 

-long, -Ig 

prints the components' relocation values (also printed in 
the default brief mode), compilation times, and source 
languages . 

-name STR, -nm STR 

is used to indicate that STR is really a component name, 
even though it appears to be an octal offset. 

-no_header, -nhe 

omits all headers, printing only lines concerning the 
components themselves. 
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Name: pr int_link__info , pli 

The pr int_link__info command prints selected items of information 
for the specified object segments. 

Usage 

pr int_link__inf o paths {-control_args} 



where : 

1. paths 



are the pathnames of object segments. 



2. control__args 

can be chosen from the following list. (See "Note" 
below. ) 

-length, -In 

- print only the lengths of the sections in path_i. 
-entry, -et 

print only a listing of the path^ external definitions, 

giving their symbolic names and their relative addresses 
within the segment. 

-link, -Ik 

print only an alphabetically sorted listing of all the 
external symbols referenced by path_i. 

-long 

prints more information- when the header is printed.- 
Additional information includes a listing of source 
programs used to generate the object segment, the contents 
of the "comment" field of the symbol header (often 
containing compiler options) , and any unusual values in 
the symbol header. 

-header, -he 

prints the header (The header is not printed by default, 
if the -length, -entry, or -link control argument is 
specified .) 

-no__header 

suppresses printing of the header. 

Note 

Control arguments can appear anywhere on the command line and 
apply to all pathnames. 
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link info, pli 



Example 



i pr int__link__info program -long -length 

program 07/30/76 1554.2 edt Fri 



Object Segment >udd>Work>Wilson>program 
Created on 07/30/76 0010.1 edt Fri 
by Wilson. Work .a 

using Experimental PL/I Compiler of Thursday, July 26, 1976 at 21:38 



Translator : 

Comment : 

Source : 
07/30/76 0010.1 
12/15/75 1338.1 
06/30/75 1657.7 
10/06/72 1206.8 
05/18/72 1512.4 
01/17/73 1551.4 

Attr ibutes : 



PL/I 

map table optimize 

edt Fri >user_dir_dir>work>Wilson>s>s>program.pll 

edt iMon > 1 ibr ary_d ir__d ir> include> linkdcl . incl . pll 

edt Mon >library_dir_dir>include>object_info. incl .pll 

edt Fri >library__dir_dir> include>source__map. incl .pll 

edt Thu >library__dir_dir> include>symbol_block .incl .pll 

edt Wed >library_dir__dir> inclade>pll_symbol_block .incl 
relocatable , procedure , standard 



Start 
Length 



Ob j ect 
0 

11110 



Text 
0 

3450 



Def s 
3450 
150 



Link 
3620 
36 



Symb 
3656 
5215 



Static 
3630 
0 



<ready> 



Also printed is: 

Severity, if it is nonzero. 
Sntrybound, if it is nonzero. 
Text Boundary, if it is not 2. 
Static Boundary, if it is not 2. 
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Name ; resolve__l inkage__error , rle 

The resolve__linkage__error command is invoked to satisfy the 
linkage fault after a process encounters a linkage error. The program 
locates the virtual entry specified as an argument and patches the 
linkage information of the process so that when the start command is 
issued the process continues as if the original linkage fault had 
located the specified virtual entry. 



resolve__linkage__error virtual_entry 



where virtual^entry is a 'virtual entry specifier. 



Notes 

For an explanation of virtual entries, see the description of the 
cv___entry_ subroutine. 



Examples 

I myprog 

Error: Linkage error by > udd>m> vv>myprog 1 123 
referencing subroutines entry 
Segment not found. 

r 1234 2.834 123.673 980 level 2, 26 

I rle mysub$mysub_entry 

r 1234 0.802 23.441 75 level 2, 26 

I start 

... myprog is running 
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trace stack, ts 



Name : trace_stack, ts 

The trace_stack command prints a detailed explanation of the 
current process stack history in reverse order {most recent frame 
first) . For each stack frame, all available information about the 
procedure that established the frame (including, if possible, the 
source statement last executed) , the arguments to that (the owning) 
procedure, and the condition handlers established in the frame are 
printed. For a description of stack frames, see "Multics Stack 
Segments" in SectionllV of the MPM Subsystem Writers' Guide. 



The trace_stack command is most useful after a fault or other 
error condition. If the command is invoked after such an error, the 
machine registers at the time of the fault are also printed, as well 
as an explanation of the fault. The source line in which it occurred 
can be given if the object segment is compiled with the -table option. 



Usage 

trace_stack { -control_args} 



where control_args can be selected from the following: 
-brief, -bf 

suppresses listing of arguments and handlers. This 
control argument cannot be specified if -long is also 
specified as a control argument. 

-long, -Ig 

prints octal dump of each stack frame. 

-depth N, -dh N 

dumps only N frames. 



Output Format 

When trace_stack is invoked, it first searches 
backward through the stack for a stack frame containing 
saved machine conditions as the result of a signalled 
condition. If such a frame is found, tracing proceeds 
backward from that point; otherwise, a comment is printed 
and tracing begins with the stack frame preceding 
trace stack. 



If a machine-conditions frame is found, trace_stack 
repeats the system error m.essage describing the fault. 
Unless the -brief control argument is specified, 
trace_stack also prints . the source line and faulting 
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instruction and a listing of the machine registers at the 
time the error occurred. 



The command then performs a backward trace of the 
stack, for N frames if the -depth N argument was 
specified, or else until the beginning of the stack is 
reached , 



For each stack frame, trace_stack prints the offset 
of the frame, the condition name if an error occurred in 
the frame, and the identification of the procedure that 
established the frame. If the procedure is a component of 
a bound segment, the bound segment name and the offset of 
the procedure within the bound segment are also printed. 



The trace_stack command then attempts to locate and 
print the source line associated with the last instruction 
executed in the procedure that owns the frame (that is, 
either a call forward or a line that encountered an 
error) . The source line can be printed only if the 
procedure has a symbol table (that is, if it was compiled 
with the -table option) and if the source for the 
procedure is available in the user's working directory. 
If the source line cannot be printed, trace_stack prints a 
comment explaining why. 



Next, trace__stack prints the machine instruction last 
executed by the procedure that owns the current frame. If 
the machine instruction is a call to a PL/I operator, 
trace^stack also prints the name of the operator. If the 
instruction is a procedure call, trace__stack suppresses 
the octal printout of the machine instruction and prints 
the name of the procedure being called. 



Unless the -brief control argument is specified, 
trace__stack lists the arguments supplied to the procedure 
that owns the current frame and also lists any enabled 
condition, default, and clean-up handlers established in 
the frame. 



If the -long control argument is specified, 
trace_stack then prints an octal dump of the stack frame, 
with eight words per line. 
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Example 

After a fault that reenters the user environment and 

reaches command level, the user invokes the trace_stack 
command. 



For example, after quitting out of the list command, 
the following process history might appear: 



I list 

Segments=8, Records=3 

rew 0 mailbox 

r w 

QUIT 

trace_stack 

quit in ipc_$block i 156 

( > sy s tem_l ib r a r y__l > bo und_command_l oo p__ ! 1 56 ) 
No symbol table for ipc__ 
156 400010116100 cmpq pr4lI0 

Machine registers at time of fault 

pro (ap) 26314656 pll_operators_$operato ratable ! 162 

(external symbol in separate nonstandard 
text section) 



prl 


(ab) 


103 1264 






scsl 264 


pr2 


(bp) 


14 1 12200 






as_linkagel 12200 


pr3 


(bb) 


113 10 






tc data 10 


pr4 


dp) 


253 12250 






IBBBJGjFkPBWcNZ .area. linker! 2250 












(internal staticiO for ipc ) 


pr5 


(lb) 


244 13614 






stack 413614 


pr6 


(sp) 


244 13500 






stack__4 1 3500 ( -> "kcpMbLH +0000000") 


pr7 


(sb) 


244 10 






stack_4 i 0 


xO 


73 


xl 


0 


x2 


0 x3 600000 


x4 


0 


x5 


32 


x6 


3033 x7 4 



a 000000000000 q 000000000004 e 0 
Timer reg - 1746005, Ring alarm reg - 0 

SCU Data: 

4030 400270250011 000000000021 400270000000 000000672000 
000156000200 000154000700 002250370000 600044370120 

Connect Fault (21) 

At: 270 1156 ipc__!l56 (bound_command_loop__! 156) 
On: cpu a (#0) 
Indicators: '^bar 
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APU Status: xsf, sd-on, pt-on, fabs 
CU Status: rfi, its, fif 
Instructions : 

4036 002250 3700 00 epp4 2250 

4037 6 00044 3701 20 epp4 pr6|44,* 

Time stored: 08/02/77 1635.5 edt Tue (104541674361226602) 
Ring: 4 

Backward trace of stack from 244 13500 



3500 quit i pc__$ block i 156 (bound__command__loop__i 156) 
No symbol table for ipc__ 
156 400010116100 cmpq pr4ll0 

ARG 1 : 253 15704 I BBBJG j FkPBWcNZ .area . 1 inke r I 5704 
ARC 2: 244 13152 stack_4 13152 
ARG 3: 0 



2720 tty_$ tty_get__linel 2442 (bound__iox__l 11546) 

No symbol table for tty__ 
call__ext__o ut to ipc__$block 

ARG 1: 25314320 I BBBJG j FkPBWcNZ . area . 1 inke r i 4 320 

(internal static|154 for find___iocb) 
ARG 2: 244 1 2660 st3Ck_4 12660 ( -> "fo stuff") 
ARG 3: 128 
ARG 4: 0 
ARG 5: 0 



2400 listen_$listen_l 461 (bound_coramand_loop_l 1 325) 

No symbol table for listen^ 
call__ext__out to iox_$get_line 

ARG 1 : " " 

on "cleanup" call listen_l256 (bound_command_loop__l 112 2) 



2100 process_overseer_$process_overseer__| 473 (bound__command_loop__| 214 

No symbol table for process_over seer_ 
call__ext__out_desc to listen_$listen_ 
Argument list header invalid, 
on "any__other" 

call standard_defaul t_handler_$standard__defaul t_handler_3 
(external symbol in separate nonstandard text section) 



2000 user ini t_admin__$user_ini t_admin__i 36 (bound_command_loop_| 21676) 

No symbol taHle for user___ini t_admin_ 
21676 700036670120 tsp4 pr7 136,* alm_call 

No arguments. 

End of trace. 
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r 1635 1.756 40.790 207 level 2, 9 
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Name: area^status 

The area^status command is used to display certain information 
about an area." 



Usage 

area_status area name {-control args} 



where : 

1. area_name 

is a pathname specifying the segment containing the area 
to be looked at. 

2. control_args 

can be chosen from the following: 

-trace 

displays a trace of all free and used blocks in the area. 

-offset N, -ofs N 

specifies that the area begins at offset N (octal) in the 
given segment. 

-long, -Ig 

dumps the contents of each block in both octal and ASCII 
format. 

Note 

If the area has internal format errors, these are reported. The 
command does not report anything about (old) buddy system areas except 
that the area is in an obsolete format. 
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Name ; cancel_cobol__prog ram , ccp 

The cancel_cobol_program command causes one or more programs in 
the current COBOL run unit to be cancelled. Cancelling ensures that 

the next time the program is invoked within the run unit, its data is 
in its initial state. Any files that have been opened by the program 
and are still open are closed and the COBOL data segment is truncated. 
Refer to the run^cobol command for information concerning the run unit 
and the COBOL runtime environment. 



Usage 

cancel cobol program names {-control arg} 



where : 

1. names 

are the reference names of COBOL programs that are active 
in the current run unit. If the name specified in the 
PROG-ID statement of the program is different from its 
associated name_i argument, name^ must be in the form 
refname$PROG-ID. 

2. control__arg 

may be -retain_data or -retd to leave the data segment 
associated with the program intact for debugging purposes. 
(See "Notes" below.) 



Notes 

The results of the cancel cobol_prog ram command and the execution 

of the CANCEL statement from wTthin a COBOL program are similar. The 
only difference is that if a name_i argument is not actually a 

component of the current run unit, an error message is issued and no 

action is taken; for the CANCEL statement, no warning is given in such 
a case. 



To preserve program data for debugging purposes, the -retain data 
control argument should be used. The data associated witH the 
cancelled program is in its last used state; it is not restored to its 
initial state until the next time the program is invoked in the run 
unit. 



Refer to the following related commands: 
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display cobol___run__unit , dcr 
stop_coBol__run , scr 
run cobol, rc 
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Name ; create^area 

The create ar« 
user-specified "area management control information. 

Usage 

create_^area virtual__ptr {-control^args} 
where : 

1. virtual ptr 

Ts a virtual pointer to the area to be created. The 
syntax of virtual pointers is described in the cv_ptr_ 
subroutine description. If the segment already exists, 
the specified portion is still initialized as an area. 

2. control^args 

can be chosen from the following: 

-no^f ree ing 

~" allows the area management mechanism to use a faster 
allocation strategy that never frees. 

-dont free 

Ts used during debugging to disable the free mechanism. 
This does not affect the allocation strategy. 

-zero on__alloc 

Tnstructs the area management mechanism to clear blocks at 
allocation time. 

-zero^on__f ree 

Tnstructs the area management mechanism to clear blocks at 
free time. 

-extend 

causes the area to be extensible, i.e., span more than one 
segment. This feature should be used only for perprocess, 
temporary areas. 

-size N 

specifies the octal size, in words, of the area being 
created or of the first component, if extensible. If this 
control argument is omitted, the default size of the area 
is the maximum size allowable for a segment. 

-id STR 

specifies a string to be used in constructing the names of 
the components of extensible areas. 
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Name: create__^data__segment , cds 

The create_data_segment command translates a create_data_segment 
source program" (CDS program) into an object segment. A listing 
segment is optionally created. These results are placed in the user's 
working directory. This command cannot be called recursively. 



The source for create data^segment programs is standard PL/I with 
the restriction that the program include a call to the 
create^data^segment^ subroutine. The create data_segment__ subroutine 
creates a standard object segment from PL/I "^ata structures passed to 
it as parameters. These data structures can be initialized with 
arbitrarily complex PL/I statements in the CDS program. (See the MPM 
Subroutines for a description of the create data segment subroutine.) 



Usage 

create data segment path {-control arg} 



where : 

1. path 

is the pathname of a CDS segment that is to be translated 
into an object segment. If patn does not have a cds 
suffix, one is asssumed. However, the cds suffix must be 
the last component of the name of the source segment, 

2. control_arg 

can be -list (-Is) to produce a source listing of the CDS 
program used to generate the data segment followed by 
object segment information (as printed by the 
pr int_link_inf o command described in the MPM Subsystem 
Writers' Guide) about the actual object segment created. 



Note 

Since the create data^segment command invokes the PL/I compiler 
to first compile the ^DS segment, any errors that the compiler finds 
are reported by its standard technique. If any errors with a severity 
greater than 2 occur, the CDS run is aborted and an object segment is 
not created. 
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Name: cumulative^page^trace, cpt 

TijS CUiuUiatiVS pags trscs cominarid sccuinulatss pa^s tracs data so 
that the total set o"f pages used during the invocation of a command or 
subsystem can be determined. The command accumulates data from one 
invocation of itself to the next. Output from the command is in 
tabular format showing all pages that have been referenced by the 
user's process. A trace in the format of that produced by the 
page trace command can also be obtained. 



The cumulative_page_trace command operates by sampling and 
reading the system trace array after invocation of a command and at 
repeated intervals. Control arguments are given to specify the 
detailed operation of the cumulative page trace command. 



The command line used to invoke the cumulat ive^page^trace command 
includes the command or subsystem to be traced as weTl as optional 
control arguments. 



Usage 

cumulative page trace command line {-control args} 



where : 

1. command line 

Ts a character string to be interpreted by the command 
processor as a command line. If this character string 
contains blanks, it must be surrounded by quotes. All 
procedures invoked as a result of processing this command 
line are metered by the cumulative_page__trace command. 

2. control^args 

may be chosen from the following: 

-count, -ct 

prints the accumulated results, giving the number of each 
page and the number of faults for each page. 

-flush 

clears primary memory before each invocation of the 
command line and after each interrupt. This helps the 
user determine the number of page faults but increases the 
cost* 

-interrupt N -int N 

interrupts execution every M virtual CPU milliseconds for 
page fault sampling. 



cumulative page trace^cpt 



-long, -Ig 

produces output in long format, giving full pathnames, 
-loop N 

calls the command to be metered N times, 
-print, -pr 

prints the accumulated results, giving the number of each 
page referenced, 

-pr in t_l inkage faults 

prints aXl accumulated linkage faults and calls to the 
hcs_$make__ptr entry point, 

-reset, -rs 

resets the table of accumulated data. If the table is not 
reset, data from the current use of cumulative_page__trace 
is added to that obtained earlier in the process. 

-short, -sh 

formats output for a line length of 80. 

-sleep N 

waits for N seconds after each call to the command being 
metered. 

-timers 

includes all faults between signal and restart. " 
-total, -tt 

prints the total number of page faults, the total number 
of segment faults, and the number of pages referenced for 
each segment. 

-trace__l inkage___f aul ts 

accumulates linkage faults information along with page and 
segment fault information. 

-trace path 

writes the trace on the segment named path using an I/O 
switch named cpt.out; cumulative_page__trace attaches and 
detaches this switch. " 



Notes 

At least one of three generic operations must be requested. They 
may all be combined and, if so, are performed in the following order: 
resetting the table of accumulated data, calling the command to be 
metered, applying the specified control arguments, and printing the 
results in the specified format. 
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The default mode of operation permits no interrupts for page 
fault sampling. If the command or subsystem to be metered will take 
more than several hundred page faults^ linkage faults, or other system 
events that are indicated in the page trace array, it is recommended 
that interrupts be requested. If the user does not know a suitable 
value for the -interrupt control argument, the value recommended is 
400 milliseconds. If this figure is too large, messages indicate that 
some page faults may have been missed; a smaller value can then be 
chosen. The cost of a smaller value is high and may cause additional 
side effects. If the command or subsystem to be metered includes the 
taking of CPUT interrupts, then the -timers control argument should be 
given. This control argument causes some of the page faults of the 
metering mechanism to be included as well. 



Only one of the control arguments -print, -count, or -total may 
be given. Each of these control arguments produces printed output in 
a different format. If more than one format is desired, the command 
must be invoked once for each format. 



Examples 

The command line: 

cpt "pll test" -interrupt 400 -trace trace__out 

calls the pll command to compile the program named test, requesting an 
interrupt every 400 milliseconds to obtain page trace information. 
Trace information is placed in a segment named trace^out. 

The command line: 

cpt "list -pn >udd>Multics" -loop 2 -sleep 10- 
calls the list command twice, and sleeps for 10 seconds between calls. 



The command line: 
cpt -print 

prints the accumulated results of previous metering. 
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Name ; cv_ptr_ 

The cv_ptr_ subroutine converts a virtual pointer to a pointer 
value. A virtual pointer is a character string representation of a 
pointer value. The types of virtual pointers accepted are described 
under "Virtual Pointers" below. 



Usage 

declare cv_ptr__ entry (char(*), fixed! bin ( 35 ) ) returnsi (ptr) ; 
ptr^value - cv__ptr__ (vptr, code); 

where : 

1. vptr is the virtual pointer to be converted, (Input) 

See "Virtual Pointers" below for more information. 

2. code is a standard status code. (Output) 

3. ptr^value is the pointer that results from the conversion. 

" (Output) 

Entry : cv__ptr_$ terminate 

This entry point is called to terminate the segment that has been 
initiated by a previous call to cv_ptr__. 

Usage 

declare cv_ptr__$ terminate (ptr) ; 
call cv_ptr_$ terminate {ptr__value) ; 

where ptr value is the pointer returned by the previous call to 
cv_ptr_. Tinput) 

Notes 

Pointers returned by the cv_^ptr__ subroutine cannot be used as 
entry pointers in calls to cu^$gen__call or cu $make_entry_^value . The 
cv_ptr_ subroutine constructs the returned poTnter to a "segment in a 
way that avoids copying of the segment's linkage and internal static 
data into the combined linkage area. The cv^entry_^ subroutine is used 
to convert virtual entries to an entry value. 
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The segment pointed to by the returned ptr^value is initiated 
with a null reference name. The cv__ptr__$ terminate entry point should 
be called to terminate this null reference name. 



Virtual Pointers 

The cv^ptr subroutine converts virtual pointers that contain one 
or two components — a segment identifier and an optional offset into 
the segment. Altogether, fourteen forms are accepted. They are shown 
in the table below. 



In the table that follows, W is an octal word offset from the 
beginning of the segment. It may have a value from 0 to 777777 
inclusive. B is a decimal bit offset within the word. It may have a 
value from 0 to 35 inclusive. 



iNoC TO be KeproQUcea a-iu c ^i. 
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Vi rtual 
?o inter 



Interpretation 



path! W(3) 

path! W 
path I 
path 

path! entry pt 

ref^name$entry_pt 

ref__name$W(B) 

ref_^name$W 

ref___name$ 
segno 1 W(B) 

segno 1 W 
segno 1 
segno 

segno i entry__pt 



points to octal word W, decimal bit B of segment 
identified by absolute or relative pathname path. 

same as pa th ! W(0 ) . 

same as pa th I 0 {0 ) . 

same as path I 0 (0 ) . 

points to word identified by entry point entry__pt 
in segment identified by path, 

points to word identified by entry point entry^pt 
in segment whose reference name is ref__name, 

points to octal word W, decimal bit B of segment 
whose reference name is ref__name. 

same as ref_^name$W (0 ) . 

same as ref_name$0 (0 ) . 

points to octal word W, decimal bit 3 of segment 
whose octal segment number is segno. 

same as segno 1W(0), 

same as segnolO(O). 

same as segnolO(O). 

points to word identified by entry point entry__pt 
in segment whose octal segment number is segno. 



A null pointer is represented by the virtual pointer 77777 11, by -1 i 1 , 
or by -1. 



Not To Be Reproduced 



A-11 



F21 



delete external variables 



Name : del ete__ex ternal^var iables 

The delete external^var iables command deletes from the user's 
name space specTfied vaTiables managed by the system for the user. 
All links to those variables are unsnapped and their storage is freed. 



delete^external^variables names {-control^arg} 



where: 

1. names 

are the names of the external variables, separated by 
spaces, to be deleted. 

2. control arg 

Ts -unlabeled__comraon (or -uc) to indicate unlabeled (or 
blank) common. 
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The display__cobol__run_unit command displays the current state of 
a COBOL run unit. The minimal information displayed tells which 
programs compose the run unit. Optionally, more detailed information 
can be displayed concerning active files, data location, and other 
aspects of the run unit. Refer to the run__cobol command for 
information concerning the run unit and the COBOL runtime environment. 



Usage 

display cobol run unit {-control args} 



where control^args may be chosen from the following list: 
-long , -Ig 

causes more detailed information about each COBOL program 
in the run unit to be displayed. 

-files 

displays information about the current state of the files 
that have been referenced during the execution of the 
current run unit. 

-all, -a 

prints information" about all programs in the run unit, 
including those that have been cancelled. 



Note 

Refer, to the following related -commands: 



run__cobol , rc 
stop_^cobol__run , scr 
cancel cobol program, ccp 
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Name: d isplay_pll io^err , dpe 

The display pllio error command is designed to be invoked after 
the occurrence o"? an ijo error signal during a PL/I I/O operation. It 
describes the most recent file on which a PL/I I/O error was raised 
and displays diagnostic information associated with that type of 
error . 



Usage 



Example 

The command line: 

display^^pll io__error 
might respond with the following display: 

Error on file afile 
Title: vfile_ afile 

Attributes: open input keyed record sequential 
Last i/o operation attempted: write from 

Attempted "write" operation conflicts with file "input" attribute. 
Attempted "from" operation conflicts with file "input" attribute. 



Not To Be Reproduced 



A-14 



F21 



dump segment^ ds 



Name ; dump segment, ds 

The dump__segment command prints, in octal or hexadecimal format, 
selected portions of a segment. It prints out either four or eight 
words per line and can optionally be instructed to print out an edited 
version of the ASCII, BCD^ EBCDIC (in 8 or 9 bits), or 4-bit byte 
representation. 

Usage 

dump^segment path {first} {n__words} {-control^args} 

where J 
1. path 

is the pathname or (octal) segment number of the segment 
to be dumped. If path is a pathname, but looks like a 
number, the preceding argument should be the -name (or 
-nm) control argument (see below), 

2e first 

is the (octal) offset of the first word to be dumped. If 
.bc^h first and n__word3 are omitted, the entire segment is 
d Limped. 

3 . ^^^Q s 

is the (octal) number of words to be dumped. If first is 
supplied and n__words is omitted, 1 is assumed. 

4. control__arg s 

can be chosen from the following: 

-4bit 

prints out a translation of the octal or hexadecimal dump 
based on the Multics unstructured 4-bit byte. The 
translation ignores the first bit of each 9-bit byte and 
uses each of the two groups of four bits remaining to 
generate a digit or a sign. 

-address, -add 

prints the address (relative to the base of the segment) 
with the data. This is the default. 

-bed 

prints the BCD representation of the words in addition to 
the octal or hexadecimal dump. There are no nonprintable 
BCD characters, so periods can be taken literally. 

-block N, -bk N 

dumps words in blocks of N words separated by a blank 
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line. The offset, if being printed, is reset to initial 
value at the beginning of each block. 

-character, -ch, -ascii 

prints the ASCII representation of the words in addition 
to the octal or hexadecimal dump. Characters that cannot 
be printed are represented as periods. 

-ebcdic9 

prints the EBCDIC representation of each 9-bit byte in 
addition to the octal or hexadecimal dump. Characters 
that cannot be printed are represented by periods. 

-ebcdicS 

prints the EBCDIC representation of each eight bits in 
addition to the octal or hexadecimal dump. Characters 
that cannot be printed are represented by periods. If an 
odd number of words is requested to dump, the last four 
bits of the last word do not appear in the translation. 

-header, -he 

prints a header line containing the pathname 'or segment 
number) of the segment being dumped as well as the 
date-time printed. The default is to print a header only 
if the entire segment is being dumped, i.,e., r.aither the 
first nor the n__words arguments is specified. 

-hexS 

print.s the dumped words in hexadecimal .^ith nine 
hexadecimal digits per word rather than octal with 12 
octal digits per word. 

-hex9 

prints the dumped words in hexadecimal witn eight 
hexadecimal digits per word rather than 12 octal digits 
per word. Each pair of hexadecimal digits corresponds to 
the low-order eight bits of each 9-bit byte. 

-long, -Ig 

prints eight words on a line. Four is the default. This 
control argument cannot be used with -character, -bed, 
-4bit, -ebcdicS, -ebcdic9, or -short. (Its use with these 
control arguments, other than -short, results in a line 
longer than 132 characters.) 

—name, — nm 

indicates that the following argument is a pathname even 
though it may look like an octal segment number, 

-no address, -nad 

does not print the address. 
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-no__header, -nhe 

suppresses printing of the header line even though the 
entire segment is being dumped. 

-no^offset, -nofs 

" does not print the offset. This is the default, 

-offset N, -ofs N 

prints the offset (relative to N words before the start of 
data being dumped) along with the data. If N is not 
given, 0 is assumed. 

-short, -sh 

compacts lines to fit on a terminal with a short line 
length. Single spaces are placed between fields, and only 
the two low-order digits of the address are printed, 
except when the high-order digits change. ' This shortens 
output lines to less than 80 characters. 



Note 

Only -one of the control arguments: -ebcdicS, 
-ebcdic9, -character, -bed, or -4bit can be specified. 
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Name 



io call, io 



The io__call command performs an operation on a designated I/O 
switch. 



Usage 



io_call opname switchname {args} 



where: 

1. opname 



designates the operation to be performed. 



2. switchname 

is the name of the I/O switch. 



3. args 



may be one or more arguments, depending on the particular 
operation to be performed. 



The opnames permitted, followed by their alternate forms where 
applicable, are: 



attach 

close 

control 

delete^record , delete 

detach__iocb , detach 

destroy iocb 

find^iocb 

get_'chars 

get_line 

modes 

move attach 



look__iocb 
open 

position 

print iocb 

put_c"Ear s 

raad__key 

read__ length 

reader ecord , read 

rewr ite^record , rewrite 

seek_key 

write record, write 



Usage is explained below under a separate heading for each 
designated operation. The explanations are arranged functionally 
rather than alphabetically. 



Unless otherwise specified, if a control block for the I/O switch 
does not already exist, an error message is printed on error_output 
and the operation is not performed. If the requested operation is not 
supported for the switch's attachment and/or opening, an error message 
is printed on error output. 
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The explanations of the operations cover only the main points of 
interest and, in general, treat only the cases where the I/O switch is 
attached to a file or device. For full details see the descriptions 
of the iox_ subroutine and the I/O modules in the MPM Subroutines and 
Section V, "Input and Output Facilities," in the MPM Reference Guide. 



Operation ; attach 

io^call attach switchname modulename {args} 



where : 

1. modulename 

is the name of the I/O module to be used in the 
attachment. If modulename contains less-than (<) or 
greater-than (>) characters, it is assumed to be a 
pathname, otherwise, it is a reference name. 

2. args 

may be one or more arguments, depending on what is 
permitted by the particular I/O module. 



This command attaches the I/O switch using the designated I/O 
module. The attach description is the concatenation of modulename and 
args separated by blanks. The attach description must conform to the 
requirements of the I/O module. If the I/O modulename is specified by 
a pathname, it is initiated with a reference name equal to the 
entryname. If the entryname or reference name does not contain a 
dollar sign ($) , the attachment will be made by calling 
raodulename$modulenameattach , If a dollar sign is specified, the entry 
point specified is called. See "Entry Point Names" in the MPM 
Reference Guide. 



If a control block for the I/O switch does not already exist, one 
is created. 



Operation ; detach iocb, detach 
io call detach switchname 



This command detaches the I/O switch. 
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Operation ; open 

io^call open switchname mode 

where mode is one of the following opening modes, which may be 
specified by its full name, or by an abbreviation: 

stream^input , si keyed__sequential_ input , ksqi 

stream__output , so keyed__sequential__output , ksqo 

stream""input_output , sio keyed__^sequential^update , ksqu 

sequential_output , sqo d ir ect__output , do 

sequential_input__output , sqio d irect^update , du 
sequential^update , squ 

This command opens the I/O switch with the specified opening 

mode. 



Operation ; close 

io_^call close switchname 

This command closes the I/O switch. 

Operation ; get^line 

io_^call get__line switchname {N} {-control args} 



where : 
1. N 



is a decimal number greater than zero specifying the 
maximum number of characters to be read. 



2. control args 

can be selected from the following: 

-segment path {offset}, -sm path {offset} 

specifies that the line read from the I/O switch is to be 
stored in the segment specified by path, at the location 
specified by offset. 

-nnl 

specifies that the newline character, if present, is 
deleted f romr the end of the line. 
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-nl 

specifies that a newline character is added to the end of 
the line if one is not present. 

-lines 

specifies that the offset, if given, is measured in lines 
rather than characters. This control argument only has 
meaning if the -segment control argument is also 
specified. 



This command reads the next line from the file or device to which 
the I/O switch is attached. If N is given, and the line is longer 
than N, then only the first N characters are read. 



If the -segment control argument is not specified, the line read 
is written onto the .1/0 switch use r__^output , with a newline character 
appended if one is not present and -nnl has not been specified. 



If the -segment control argument is specified, the line is stored 
in the segment specified by path. If this segment does not exist, it 
is created. If offset is specified, the line is stored at that 
position relative to the start of the segment. This is normally 
measured in characters, unless -lines has been used. If offset is 
omitted, the line is appended to the end of the segment. The bit 
count of the segment is always updated to a point beyond the newly 
added data. 

Operation ; get^chars 

io call get chars switchname N {-control args} 



where : 
1. N 



is a decimal number greater than zero specifying the 
number of characters to read. 



2. control__args 

can be selected from the same list as described under the 
get__line operation. 



This command reads the next N characters from the file or device 
to which the I/O switch is attached. The disposition of the 
characters read is the same as described under the get line operation; 
that is, they are written upon user__output if the -segment control 
argument is not specified, or stored in a segment if the -segment 
control argument is specified. 
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Operation ; put__chars 

io call put chars switchname {string} {-control args} 



where : 

1. string 

may be any character string. 

2. control^args 

can bs selected from the following: 

-segment path {length}, -segment path {offset} {length}, 

-sm path {length}, -sm path {offset} {length} 

specifies that the data for the output operation is to be 
found in the segment specified by pathname. The location 
and length of the data may be optionally described with 
offset and length parameters. 

-nnl 

specifies that a newline character is not to be appended 
to the end of the output string. 

-nl 

specifies that a newline character is to be added to the 
end of the output line if one is not present. 

-1 ines 

specifies that offsets and lengths are measured in lines 
instead of characters. 



The string parameter and the -segment control argument are 
mutually exclusive. If a string is specified, the contents of the 
string are the data output to the I/O switch. If the -segment control 
argument is specified, the data is taken from the segment specified by 
path, at the offset and length given. If offset is omitted, the 
beginning of the segment is assumed. If length is omitted, the entire 
segment is output. 



If the I/O switch is attached to a device, this command transmits 
the characters from the string or the segment to the device. If the 
I/O switch is attached to an unstructured file, the data is added to 
the end of the file. The -nl control argument is the default on a 
put chars operation: a newline character is added unless one is 
already present, or the -nnl control argument is specified. 
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Operation : read^record, read 

io__call read record switchname N {-control args} 



where : 
1. N 



is a decimal integer greater than zero specifying the size 
of the buffer to use. 



2, control__args 

can be selected from the same list as described under the 
get line operation. 



This command reads the next record from the file to which the I/O 
switch is attached into a buffer of length N. If the -segment control 
argument is not specified, the record (or the part of it that fits 
into the buffer) is printed on use r__output . If the -segment control 
argument is specified, the record is stored in a segment as explained 
under the get__chars operation. 

Operation ; wr i te__record , write 

io__call wr ite__record switchname {string} {-control^args} 



where : 

1. string 

is any character string. 

2. control_args 

may be selected from the same list as described under the 
put chars operation. 



This command adds a record to the file to which the I/O switch is 
attached. If the string parameter is specified, the record is equal 
to the string. If the -segment control argument is specified, the 
record will be extracted from the segment as described under the 
put__chars operation. In either case, the -nnl control argument is the 
default: a newline character is added only if the -nl control 
argument is specified. If the file is a sequential file, the record 
is added at the end of the file. If the file is an indexed file, the 
record's key must have been defined by a preceding seek key operation. 
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Operation ; rewr i te_record , rewrite 

io call rewrite record switchname {string} [ — control args}. 



where : 

1. string 

is any character string. 

2. control_args 

may be selected from the same list as described under the 
put chars operation. 



This command replaces the current record in the file to which the 
I/O switch is attached. The new record is either the string 
parameter, or is taken from a segment, as described under the 
wr ite__record operation. The current record must have been defined by 
a preceding read record, seek key, or position operation as follows: 



read^^record 

" current record is the last record read. 

seek__key 

current record is record with the designated key. 
posi tion 

current record is the record preceding the record to which 
the file was positioned. 



Operation : delete^record , delete 

io^call delete_^record switchname 

This command deletes the current record in the file to which the 
I/O switch is attached. The current record is determined as in 
rewrite record above. 
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Operation ; position 

io^call position switchname type 



where type may be one of the following: 
bof 

sets position to beginning of file 

eof 

sets position to end of file 

forward N, fwd N, f N 

sets position forward N records or lines (same as reverse 
N) 

reverse N, rev N, r N 

sets position back N records (same as forward -N records) 

other 

any other numeric argument or pair of numeric arguments 
may be specified, but its function depends on the I/O 
module being used and may not be implemented for all I/O 
modules . 



This command positions the file to which the I/O switch is 
attached. If type is bof, the file is positioned to its beginning, so 
that the next record is the first record (structured files) , or so 
that the next byte is the first byte (unstructured files) . If type is 
eof, the file is positioned to its end;' the next record (or next byte) 
is at the end-of-file position. If type is forward or reverse the 
file is positioned forwards or backwards over records (structured 
files) or lines (unstructured files). The number of records or lines 
skipped is determined by the absolute value of N, 



In the case of unstructured files, the next byte position after 
the operation is at a byte immediately following a newline character 
(or at the first byte in the file or at the end of the file); and the 
number of newline characters moved over is the absolute value of N. 



If the I/O switch is attached to a device, only forward skips 
(where type is forward) are allowed. The effect is to discard the 
next n lines input from the device. 
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Operation ; seek__key 



io call seek key switchname key 



where key is a string of ASCII characters with 0 K I length! < !256 . 



This command positions the indexed file to which the I/O switch 
is attached to the record with the given key. The record's length is 
printed on user output. Trailing blanks in the key are ignored. 



If the file does not contain a record with the specified key, it 
becomes the key for insertion. A following write^record operation 
adds a record with this key. 



Operation ; read^key 

io_call read key switchname 



This command prints, on user output, the key and record length of 
the next record in the indexeH" file to which the I/O switch is 
attached. The file's position is not changed. 



Operation; read length 




io call read length switchname 



This command prints, on user^output, the length of the next 
record in the structured file to which the I/O switch is attached. 
The file's position is not changed. 
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Operation ; control 

io^call control switchname order {args} 



where : 

1. order 

is one of the orders accepted by the I/o module used in 
the attachment of the I/O switch. 

2, args 

are additional arguments dependent upon the order being 
issued and the I/O module being used. 



This command applies only when the I/O switch is attached via an 
I/O module that supports the control I/O operation. The exact format 
of the command line depends on the order being issued and the I/O 
module being used. For more details, refer to "Control Operations 
from Command Level" in the appropriate I/O module in the MPM 
Subroutines. If the I/O module supports the control operation and the 
paragraph just referenced does not appear, it can be assumed that only 
control orders that do not require an info structure can be performed 
with the io^call command, as a null in"ro__ptr is. used. (See the 
description of the iox__$control entry point and the I/O module's 
control operation, both in the MPM Subroutines.) 



Operation ; modes 

io__call modes switchname {string} {-control arg} 



where; 

1. str ing 

is a sequence of modes separated by commas. The string 
must not contain blanks. 

2. control^arg 

may be -brief or -bf. 



This command applies only when the I/O switch is attached via an 
I/O module that supports modes. The command sets only new modes 
specified in string, and then prints the old modes on user^output. 
Printing of the old modes is suppressed if the -brief control argument 
is used. 
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If the switch name is user_^i/o, the command refers to the modes 
controlling the user's terminal. See the I/O module tty subroutine 
description in the MPM Subroutines for an explanation oT applicable 
modes. 



Operation ; find___iocb 

io call find iocb switchname 



This command prints, on user_^output , the location of the control 
block for the I/O switch. If it does not already exist, the control 
block is created. 



Operation ; look^iocb 

io call look iocb switchname 



This command prints, on user_output, the location of the control 
block for the I/O switch. If the I/O switch does not exist, an error 
is printed. 



Operation; move attach 



io call move attach switchname switchname2 



where switchname2 is the name of a .second I/O switch. 



This command moves the attachment of the first I/O switch 
(switchname) to the second I/O switch ( switchname2) . The original I/O 
switch is left in a detached state. 



Operation ; destroy^^iocb 

io call destroy iocb switchname 



This command destroys the I/O switch by deleting its control 
block. The switch must be in a detached state before this command is 
used. Any pointers to the I/O switch become invalid. 



Operation ; print^iocb 

io call print iocb switchname 
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This command prints, on user_output, all of the data in the 
control block for the I/O switch, including all pointers and entry 
var iables , 
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Usage : 


io 


Usage 


: io 


Usage 


\ io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


: io 


Usage 


; io 


Usage 


: io 


Usage 


: io 


Usage 


« W 


Usage 


: io 


Usage 


: io 



attach switchname modulename {args} 
detach switchname 
open switchname mode 
close switchname 

get^line switchname {N} {-control^args} 

get_chars switchname N {-control___args} 

put^^chars switchname {string} {-control args} 

read^record switchname N {-control__argsT 

write^record switchname {string} { -control__args} 

rewrite^record swi tchname {string} {-control___args} 

delete__record switchname 

position switchname type 

seek__key switchname key 

read_key switchname 

read__length switchname 

control switchname order {args} 

modes swi tchname [ string} {-control_arg} 

find__iocb switchname 

look__^iocb switchname 

move attach switchname 5witchname2 

destroy___iocb switchname 

print iocb switchname 



where: 

1. switchname 

is the name of the I/O switch. 

2. modulename 

is t-he name of I/O module used in the attachment. 



3. args 



are any arguments accepted by the I/O module used in the 
attachment. 
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4. 



mode 



is one of the following modes 



str eam__input , si 
stream^output , so 
stream_^input_output , sio 
sequential_^input , sqi 

sequential]^output , sqo _ 
sequen tial_input__output , sqio direct^update , da 
sequential^^update , squ 



keyed^sequential^input , ksqi 
keyed__^sequen tial___output , ksqo 
keyed^sequential~update , ksqu 
direct_^input , di"" 

direct output, do 



6« string 



type 



is a decimal number. 



is any character string. 



sets the file position. It can be: 



bof 

eof 
other 



forward N 
reverse N 



8. 
9. 



key 
order 



is a string of ASCII characters with 0 i< I leng thl< i 256 . 



is one of the orders accepted by the I/O module used in 
the attachment of the I/O switch. 



10, control^args 

can be chosen from the following: 

-segment path {length}, -sm path {length} 
-segment path {offset}, -sm path {offset} 

-segment path {offset} {length}, -sm path {offset} {length} 
-nnl 

-nl 

-lines 
-brief, -bf 
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Name : list_external_var iables 

The 1 ist_external__var iables command prints information about 
variables managed by the system for the user, including FORTRAN common 
and PL/I external static variables whose names do not contain dollar 
signs. The default information is the location and size of each 
specified variable. 



Usage 

list external variables names {-control args} 



where : 

1. names 

are names of external variables, separated by spaces. 

2. control^args 

can be chosen from the following: 

-unlabel ed__common, -uc 

is the name for unlabeled (or blank) common. 

-long, -Ig 

prints how and when the variables were allocated, 
-all, -a 

prints information for each variable the system, is 
manag ing . 

-no__header, -nhe 

suppresses the header. 
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list temp segments 



Name: 1 ist__temp__segments 

The 1 ist__te-mp_^segments command lists the segments currently in 
the temporary "segment pool associated with the user's process. This 
pool is managed by the get__^temp^segments_ and release__temp^segments_ 
subroutines (described in the MPM Subroutines) . ~ 



Usage 

list temp segments {names} {-control arg} 



whe r e : 



names 



is a list of names identifying the 
segments are to be listed. 



programs whose temp 



control arg 

Ts -all (or -a) to list all temporary segments. If the 
command is issued with no control argument, it lists only 
those temporary segments currently assigned to some 
program. 



Examples 



To list all the segments currently in the pool, type: 



list_temp_segments -all 

5 Segments, 2 Free 

IBBBCdfghgffkkkl .temp. 0246 work 

iSBBCdffddfdffkl .temp. 0247 work 

iBBBCddffdfffhhh. temp. 0253 (free) 

IBBBCdgdgfhfgfsf . temp.0254 (free) 

iBBBCvdvfgvdgvvv. temp.0321 editor 



To list the segments currently in use, type: 



1 i s t__ t emp__ s egm en t s 

3 Segments 

IBBBCdfghgffkkkl .temp. 0246 work 
IBBBCdffddfdff kl . temp. 0247 work 
1 BBBCvdvfgvdgvvv. temp.0321 editor 
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To list segments used by the program named editor, type: 
list_temp__segments editor 

1 segment 
I BBBCvdvf gvdgvvv , temp .0321 ed i to r 
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page trace, pgt 



Name ; page__trace, pgt 

The page_^tr3ce command prints a recent history of page 
other system events within the calling process. 



Usage 

page trace {N} {-control args} 



where: 
1. N 

prints the last N system events {mostly page faults) 
recorded for the calling process. If N is not specified, 
then all the entries in the system trace list for the 
calling process are printed. Currently, there is room for 
approximately 350 entries in the system trace array. 



2. control__args 

can be chosen from the following; 

-from STR, -fm STR 

searched the trace array for a user marker matching STR. 
If one is found, printing begins with it; otherwise, 
printing begins with the first element in the array. 

-long, -Ig 

prints full pathnames where appropriate. The default is 
to print only entrynames. 

-no^header, -nhe 

suppresses the header that names each column. The default 
is to print the header. 

-output switch swname, -os swname 

wrTtes all output on the I/O switch named swname, which 
must already be attached and open for stream^output . The 
default is to write all output on the user^output I/O 
switch. 

-to STR 

stops printing if a user marker marching STR is found. 
The default is to print until the end of the array. If 
both -from and -to are specified, the from marker is 
assumed to occur before the to marker. 



Output 
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page trace, pgt 



The first column of output describes the type of trace entry. An 
empty column indicates that the entry is for a page fault. The second 
column of output is the real time, in milliseconds, since the previous 
entry's event occurred. The third column (printed for page faults 
only) is the ring number in which the page fault occurred, "^he fourth 
column of output contains the page number for entries, where 
appropriate. The fifth column gives the segment number for entries, 
where appropriate. The last column is the entryname (or pathname) of 
the segment for entries, where appropriate. 



Notes 

Since it is possible for segment numbers to be reused within a 
process, and since only segment numbers (not entrynames or pathnames) 
are kept in the trace array, the entrynames and pathnames associated 
with a trace entry may be for previous uses of the segment numbers, 
not the latest ones. In fact, the entry and pathnames printed are the 
current ones appropriate for the given segment number. 



For completeness, events occurring while inside the supervisor 

are also listed in the trace. The interpretation of these events 

sometimes requires detailed knowledge of the system structure; in 
particular, they may depend on activities of other users. For many 

purposes, the user will find it appropriate to identify the points at 

which he enters and leaves the supervisor and ignore the events in 
between. 



Typically, any single invocation of a program does not induce a 
page fault on every page touched by the program, since some pages may 
still be in primary memory from previous uses or use by another 
process. It may be necessary to obtain several traces to fully 
identify the extent of pages used. 



A count value (N) and either the -from or -to control argument 
cannot be specified in the same invocation of the page trace command. 
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print bind map 



Name ; pr int_bind_map 

The pr int^bind__map command displays all or part of the bind map 
of an object segment generated by version number 4 or subsequent 
versions of the binder. 

Usage 

print bind map path {components} {-control args} 



whe r e : 
1. path 



is the pathname of a bound object segment. 



2. components 

are the optional names of one or more components of this 
bound object and/or the bindfile name. Only the lines 
corresponding to these components are displayed. A 
component name must contain one or more nonnumeric 
characters. If it is purely numerical, it is assumed to 
be an octal offset within the bound segment and the lines 
corresponding to the component residing at that offset are 
displayed. A numerical component name can be specified by 
preceding it with the -name control argument (see below). 
If no component names are specified, the entire bind map 
is displayed. 

3. control args 

may be chosen from the following list: 

-long, -Ig 

prints the components' relocation values (also printed in 
the default brief mode) , compilation times, and source 
languages . 

-name STR, -nm STR 

is used to indicate that STR is really a component name, 
even though it appears to be an octal offset. 

-no^header, -nhe 

omits all headers, printing only lines concerning the 
components themselves. 
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print link info, pli 



Name ; pr int_link_inf o , pli 

The print link info command prints selected items of information 
for the specified o'Bject segments. 

Usage 

pr int^link^inf o paths {-control^args} 



where J 

1, paths 



are the pathnames of object segments. 



2. control__args 

can be chosen from the following list. (See "Note" 
below . ) 

-length, -In 

print only the lengths of the sections in path_i. 
-entry, -et 

print only a listing of the path_i_ external definitions, 
giving their symbolic names and their relative addresses 
withm the segment. 

-link, -Ik 

print only an alphabetically sorted listing of all the 
external symbols referenced by path^. 

-long 

prints more information when the header is printed. 
Additional information includes a listing of source 
programs used to generate the object segment, the contents 
of the "comment" field of the symbol header (often 
containing compiler options), and any unusual values in 
the symbol header. 

-header, -he 

prints the header (The header is not printed by default, 
if the -length, -entry, or -link control argument is 
specified, ) 

-no__header 

suppresses printing of the header. 

Note 

Control arguments can appear anywhere on the command line and 
apply to all pathnames. 
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Example 



I pr int_link__inf o program -long -length 

program 07/30/76 1554.2 edt Fri 



Object Segment >udd>Work>Wilson>program 
Created on 07/30/76 0010.1 edt Fri 
by Wilson. Work .a 

using Experimental PL/I Compiler of Thursday, July 26, 1976 at 21:38 



Translator: 
Comment: 
Source: 
07/30/76 

12/15/75 
06/30/75 
10/06/72 
05/18/72 
01/17/73 
Attr ibutes: 



0010.1 

1338. 1 
1657.7 
1206.8 
1512.4 
1551.4 



PL /I 

map table optimize 

edt Fri >user_dir dir>work>Wilson>s>s>program.pll 

edt Mon >library '3ir_dir> include> linkdcl . incl .pll 
edt tMon > 1 ibrary^d ir^dir > include>obj ec t__inf o . incl .pll 
edt Fri >library_dir_dir>include>soarce_map. incl .oil 
edt Thu >library_dir__dir> include>symbol_block . incl .pll 
edt Wed >library_dir_dir> include>pll_symbol__block. incl 
r el oca table, pr oc ed ur e , standard 



Start 
Leng th 



Ob j ect 
0 

11110 



Text 

0 

3450 



Def s 
3450 
150 



Link 
3620 
36 



Symb 



5215 



Static 
3630 
0 



<ready> 



Also printed is: 

Severity, if it is nonzero. 
Entrybound, if it is nonzero. 
Text Boundary, if it is not 2. 
Static Boundary, if it is not 2. 
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Name: pr int_^linkage__usage , plu 

The pr int__linkage_asage command lists the locations and size of 
linkage and static sections allocated for the current ring. This 
information is useful for debugging purposes or for analysis of how a 
process uses its linkage segments. 



A linkage section is associated with every procedure segment and 
every data segment that has definitions. 



Usage 

print linkage usage 



Note 

For standard procedure segments, the information printed includes 
the name of the segment, its segment number, the offset of its linkage 
section, and the size (in words) of both its linkage section and its 
internal static storage. 



Not To Be Reproduced 



A-39 



F21 



The probe eomuiand provides symbolic, interactive debugging 
facilities for programs compiled with PL/I, FORTRAN, or "COBOL. Its 
features permit a user to interrupt a running program at a particular 
statement, examine and modify program variables in their initial state 
or during execution, examine the stack of block invocations, and list 
portions of the source program. External subroutines and functions 
may be invoked, with arguments as required, for execution under probe 
control. The probe command may be called recursively. 



Usage 

probe { procedure^name} 



where procedure__name is an optional argument that gives the symbolic 
name of an entry to the procedure or subroutine that is to be examined 
with probe. It can take the form ref erence__name$of f set name. If no 
procedure^name argument is specified, the procedure ownTng the frame 
in which the last condition was raised is assumed, if o,ne exists; 
otherwise, an error is reported. 



Overview of Processing 

The probe command is generally used to examine an active program 
at points where execution has been suspended by one of the following: 



1. Breakpoint. Execution is temporarily halted at a point 
selected by the user and probe entered directly. Debugging 
requests associated with the breakpoint are autom.atically 
carried out and/or requests issued from the user's terminal. 
Program execution can be resumed at the point of 
interruption. 

2. Error. An error such as zerodivide or subscr iptrange can 
interrupt program execution. After an error message is 
printed, a new command level is established. The user can 
then call probe to examine the state of the program. 

3. Quit signal. A run-away or looping program can be stopped 
by issuing a quit signal. A new command level is 
established and the user can call probe to determine the 
source of the problem. 



In all of these cases, variables of all storage classes 
(including automatic) are accessible. 
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The probe command can also be used to examine a nonactive program 
— one that has never been run or that has completed execution — by 
specifying a procedure^name argument in the command line. In this 
case, the user can examine static variables and the program source. 
However, the most common use is to set breaks before actually running 
the program. 



A program to be debugged with probe must have a standard symbol 
table that contains information about variables defined in the program 
and a statement map that gives the correspondence between source 
statements and object code, A symbol table and statement map are 
produced for the languages supported if the -table control argument is 
given at compilation, (A program may also be compiled with the 
-br ief__table control argument, which produces only a statement map. 
The variables of a program compiled in this way cannot be examined 
with probe; however, the user may retrieve information about source 
statements and where the program was interrupted and also may set- 
breakpoints at particular statements,) 



Information about programs being debugged is stored by probe in a 
segment in the user's home directory called Person^id .probe where 
?erson__id is the user' s log-in name. This segment is created 
automatically when needed. 



Probe Pointers 

Three internal "pointers" are used by probe to keep track of the 
program's state. They are: 

source pointer indicates the current source-program statement 

block pointer indicates the current block 
control pointer indicates the current control point 

These values are affected by certain probe requests. A user can, 
for example, position the source pointer to a particular statement, 
then list a portion of the source program beginning at that point. 



The block pointer serves two purposes. It identifies the 
procedure, subprogram, or begin block whose variables are to be 
examined. Further, it specifies the stack frame associated with the 
block and is used to distinguish among different occurrences of an 
automatic variable in a recursively invoked procedure. The control 
pointer marks the point at which a program is suspended. 



The initial values of these pointers are determined as described 
below. If a procedure name argument is given in the command line and 
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if the designated program is active, the control and source pointers 
are set to the last statement executed, and the block pointer is set 
to the most recent invocation of the procedure. If the designated 
program is not active, then the control and source pointers are set to 
the entry statement, and the block pointer to the outermost block (but 
with no active frame) . 



If no procedure name argument is given and the default rule 
applies (i.e., a condition has been raised), then the procedure in 
which the condition was raised is used. The source and control 
pointers are set to the statement where the condition was raised, and 
the block pointer- to the block containing that statement. 



Similarly/ when probe is entered because of a breakpoint 
encountered during the execution of a program, the source and control 
pointers are set to the statement at which the break has been set; and 
the block pointer to the block containing that statement. 



Breakpoints 

A breakpoint causes a temporary interruption of program 
execution, during which debugging operations can be performed. Using 
probe requests, a user can set a' breakpoint before or after any 
statement and can associate a list of probe requests with the break. 
A break set after a statement may, in some cases, not be executed due 
to the nature of the code generated for that statement. When the 
break is encountered during execution, probe is entered and the list 
of requests interpreted automatically. These requests might, for 
example, display the value of a variable or alter its value 
(effectively allowing source level patching of the program), tell what 
line was just executed, or cause probe to read a list of requests from 
the terminal to permit the user to interactively examine the state of 
his program. When the request list associated with the break is 
exhausted, the execution of the program is resumed from the point at 
which it was interrupted. 



The implementation of a breakpoint by probe consists of patching 
a call to the probe command into the appropriate location in the 
object segment of the program. As a result, there need not be an 
active invocation of probe for a break to occur; also, breakpoints may 
be set in a program before it is run, while the program is suspended 
by another break, or before a program interrupted by a quit signal or 
error condition has been restarted. 
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Probe Requests 

A probe request consists of a keyword (or its abbreviation) that 
specifies the desired function and any arguments required by the 
particular request. 



A series of requests may be given in the form of a request list. 
Here, individual requests are separated by semicolons "or newline 
characters. 



A single request or a parenthesized request list may be preceded 
by a conditional predicate whose value determines if and when the 
requests it modifies will be executed. 



The following pages present the format and function of each probe 
request. Requests are grouped according to function. Required 
arguments are indicated for each. The syntax and semantics of generic 
arguments such as expressions, procedures, labels, and variables are 
defined under separate headings following the request descriptions. 



The following descriptions first give the name of the request and 
its abbreviated form (if any). This line is followed by the general 
format line(s) of the' request. 



BASIC REQUESTS 

1. value, V 

value expression 
value cross-section 



The request "value expression" causes the value of the given 
expression to be displayed. Allowable expressions are variables, 
builtin functions such as addr and octal, and the value returned by an 
external function. The evaluation of expressions is described later 
(following the descriptions of all the requests) under "Evaluation of 
Expressions. " 
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Examples : 

value var 

value p -> a.b ( j) .c 

value addr ( i) 
value octal (ptr) 
value function (2) 



The request "value cross-section" is used to display values 
contained in a cross-section of an array. A cross-section is 
specified by giving the upper and lower bounds of one or more 
subscripts, as in: 



value array {1:5, 1) 



The notation li5 indicates the range one through five for the 
first subscript. The example above prints array(l,l), array(2,l), 
array(5,l). More than one dimension can be iterated; for 
instance, array ^ I : 2 , 1 : 2) prints, in order, array(l,l), array(l,2), 
array(2,l), array(2,2). 



2. let, 1 

let variable = expression 

let cross-se::tion = expression 



This request sets the specified variable or array elements to the 
value of the expression. If the variable and the expression are of 
different data typ-e-^, conversion is performed according to the rules 
of PL/I. Array cross-sections are expressed as shown in the value 
request above. One array cross-section may not be assigned to 
another. 



Examples : 

let var = 2 

let array (2,3) = i + 1 
let p -> a.b(l: 2) .c = 10b 
let ptr = null 



Because of compiler optimization, the change may not take 
immediate effect- in the program, though the value request shows the 
value to be altered. 
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3. call, cl 

call procedure (arg_l, argn) 



This request calls the procedure named with the arguments given. 
If the procedure expects arguments of a certain type, those given are 
converted to the expected type; otherwise, they are passed .vithout 
conversion. The value request {see above) can be used to invoke a 
function, with the same sort of argument conversion taking place. If 
the procedure has no arguments, a null argument list, "()"/ must be 
g iven . 



Examples ; 

call sub ("abc", p -> p2 -> bv, 25o, addr(j)) 
call sub__noargs {) 
value function {"010"b) 



4. goto, g 

goto label 



This request transfers control from probe to 
specified and initiates program execution at that point. 



the s^iitement 



Examples : 



goto label__var 
goto action (3) 
goto 29 

goto $110 

goto $c,l 



transfer to value of label variable 
transfer to label constant 
transfer to statement on line 29 of 
current program 

transfer to line with label 110 in the 

FORTRAN program 

transfer to the statement following the 
current statement 



Because of compiler optimization, unpredictable results may occur 
when using this request. 



5. quit, q 
qui t 



This request causes a return to command level 
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6« continue, c 
continue 

This request restarts a program that has been suspended by a 
break. If this request is issued in any other context, probe-returns 
to its caller (generally command level) . 

SOURCE REQUESTS 
lo source, sc 



This request displays one or more statements beginning with the 
current statement (i.e., the source pointer) . If n is not specified, 
one line is printed; otherwise, n lines are printed. Only executable 
statements for which code has been generated can be listed; however, 
if a range of statements is requested, intervening text, such as 
comments and nonexecutable statements (for example, declarations), is 
included in the output. 



position, ps 

position label 
position +n 



This request sets the source pointer to the statement indicated 
by label or to an executable statement relative to the current 
statement as indicated by the value of n and displays it if the user 
is in long mode. If +n is given, the pointer is set forward n 
statements; if -n is given, the pointer is set back n statements. If 
no label or offset is given, the statement designated by the control 
pointer is assumed. 



source n 



Examples : 



posi tion 



here 



set the source ptr to the statement 
labeled here 

to the statement labeled action (3) 

to the statement on line 14 of include 

file 2 of the program 

move forward two statements in the 
source 

move back five statements 



position 
posi tion 



action (3) 
2-14 



posi 



i tion 



+2 



posi tion 



-5 
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The position request can also be used to search for an executable 
statement that contains a specified string, using the form; 



position "string" 



The search begins with the statement following the current 
statement and continues through the program, if necessary, until the 
current statement is again reached. If a match is found, the source 
pointer is set to that statement. If the specified string contains a 
quotation mark, it must be doubled when given in the request line. 
Because statements are reordered by the compiler, the search may not 
necessarily find statements in the same order as the source listing of 
the program would indicate. 



Examples : 

position "write (6,10)" locate the statement in the program 
position "str = ""a" locate str = "a 

position "q+2"; source locate and print the statement 
SYMBOL REQUESTS ^ 

1« stack, sk 



This request traces the stack backward beginning at the ith frame 
and continuing for n frames. If i is not given, then the trace begins 
with the most recent frame and continues for n frames. If no limits 
are given, the entire stack is traced. The trace lists all active 
procedures and block invocations (including quick blocks) beginning 
with the most recent. For each block, a frame or level number is 
given, as is the name of any conditions raised in the frame. 



Examples : 

stack trace the whole stack 

stack 2 trace the two most recent frames 

stack 3, 2 trace the third and second frames 



Normally, system or subsystem support procedures are not included 
in the stack trace. These may be included by specifying "all". 



Examples : 

stack all trace the whole stack including all 

support stack frames 
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stack 5,3 all 



trace 
frames 
i. r am e s 



the fifth, fourth, and third 
including all support stack 



2. use, u 

use block 



This request selects the block to be used for subsequent probe 
requests. It may be specified by the name of an entry, a label,' or a 
stack frame number (level i) . If no block is specified, then the 
block originally used (when probe was entered) is assumed. The block 
pointer is set to the specified block so that variables in that block 
can be referenced. In addition, the source pointer is set to the last 
statement executed in the block. In this way, the point at which the 
block exited can be found through use of the source request. 
Acceptable block specifications includes 



procedure name 

label 

level i 

-n 



In this context, procedure__name is the name of a procedure or 
subprogram entry point whose frame is desired; its usage is 
essentially the same as if used on the command line. A label denotes 
the block that contains the statement identified by the label or line 
number; for instance, the label on a begin statement denotes that 
begin block. If the label's block is not active, the source pointer 
is set to the statement specified. The block specification level i 
uses the block with level number i from a stack trace; -n uses the nth 
previous instance of the current block, allowing one to move back to a 
previous recursion level. If more frames are requested than actually 
exist, the last one found is used. 



Examples 



use 



sub 



use 



the block 



that procedure sub 



use 



use 
use 



use 



-999 



level 2 
-1 



label 



occupies 

use the block that contains the 
statement labeled label 
use the second frame in the stack trace 
use the previous instance of the 
current block 

use the last (oldest) instance 
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When a level is specified, the last trace mode (support 
procedures included or excluded) specified is used to find the level 
requested . 



3. symbol, sb 

symbol identifier 



This request displays the attributes of the variable specified 
and the name of the block in which its declaration is found. If the 
size or dimensions of the variable are not constant, an attempt is 
made to evaluate the size or extent expression; if the value is not 
available, an asterisk (*) is used instead. 



4. where, wh 

where source 

where block 

where control 



This request displays the current value. of one or all of the 
pointers. Source and control give the statement number of the 
corresponding statement. Block gives the name of the block currently 
being used; if the block is active, its level number is also given. 
If neither source, block, or control appears, the information for all 
three is given. 



Examples : 



where give the value of all three pointers 

where source give the value of the source pointer 



BREAK REQUESTS 

1, before, b 

before label: request 
before label: (request list) 



This request sets a breakpoint before the statement specified by 
label and causes the given request(s) to be associated with the break. 
If no label is given, the current statement is assumed. If no 
requests are given, a halt is assumed (see the halt request described 
below) . 
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When the running program arrives at the statement specified, 
probe is entered before the statement is executed, and associated 
requests are processed automatically. When all requests are done, 
execution of the program resumes at the statement before which the 
break was set. A breakpoint set before a statement takes effect 
whether the statement is arrived at in sequence or as the result of a 
branch or call from some other location. 



Examples: 

before: (value var; value var2) set a break before the current 

statement to display the value of 
the variables var and var2 

before quick: value x set a break before the statement 

labeled quick 

before set a break containing the halt 

request before the current 
statement 



The request list may extend across line boundaries if necessary. 



2. after, a 

after label: request 

after label: (request list) 



This request is the same as che before request except that the 

break is set after the designated statement. This means that the 

request list is interpreted after the statement has been executed. If 

the statement branches to another location in the program, the 

breakpoint does not take effect; also, in some cases, the break may 

not be executed due to the nature of the code generated for the 
statement . 



Notice the distinction between two breakpoints in sequence. The 
one that is after statement x is not effective when control is passed 
to statement x+1 from elsewhere. The break before statement x+i does 
take place. 
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3. halt, h 
halt 



This request causes probe to stop processing its current input 
and to read requests from the terminal. A new invocation of probe is 
created with new pointers set to the values at the time the halt 
request was executed. As part of a break request list, it enables the 
user to enter requests while a program is suspended by the break. A 
running program can be halted in this way. A subsequent continue 
request causes probe to resume what it was doing before it stopped; 
for example, finish a break request list and resume execution of the 
prog ram . 



Examples : 

before 29: halt 

after: (value a; halt; value b) 



causes the program to halt at 
statement 29 and allows the user 
to enter probe requests (the 
continue request can be used to 
restart the program) 

causes the value of a to be 
printed before the program 
halts; later, after the user 
enters a continue request, the 
value of b is printed, and the 
execution of the program is 
resumed 



4. reset, r 
reset 

reset at/after/before label 
reset procedure 
reset * 



This request deletes breaks set by the before and after requests. 
When no argument is supplied, reset deletes the current break. With a 
label argument, breaks set before and/or after a statement are 
deleted; with a procedure or asterisk (*) argument, all the breaks in 
a specified segment or all breaks in all segments, respectively, can 
■be deleted. 



Not To Be Reproduced 



A-51 



F21 



probe , pb 



Examples: 



reset 

reset at 34 

reset after 34 
reset sub 
reset * 



delete the current break 

delete breaks set before and after 

first statement on line 34 

delete the break set after line 34 

delete all breaks in sub 

delete all known breaks 



the 



5. status, St 



status 

status at/after/before label 

status procedure 

status * 



This request gives information about breaks that have been set by 
the user. The scope of the requests is similar to reset except that 
status without arguments specifies all breaks in the current program 
(the program containing the statement designated by the source 
po inter) . 



Examples: 

status list the breaks set in the current 

prog ram 

status before label give the break set before the statement 

at label 

status sub list the breaks set in sub 

status * list the procedures that have breaks 

set in them 



6. pause, pa 



pause 



This request is equivalent to "halt; reset" in a break request 
list. It causes the procedure to execute a break once and then reset 
it. If the statement after which the break is set transfers 
elsewhere, the break does not occur and remains set until encountered 
sometime in the future or explicitly reset at some other point. 
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7. step, s 
step 



This request enables the user to step through his program one 
statement at a time. It sets a break consisting of a pause request 
after the next statement to be executed (as indicated by the control 
pointer) and resumes the execution of the program as with a continue 
request . 



MISCELLANEOUS REQUESTS 



1. mode 



mode brief 
mode long 



This request turns the brief message mode on or off. In brief 
mode, most messages generated by probe are shortened and others are 
suppressed altogether. The default is long. 

2. execute, e 

execute "string" 

This request passes one or more Multics command lines, 
represented above by "string", to the command processor for execution. 



3. acknowledge 



This request causes probe to identify itself by printing "probe" 
on the terminal. It may be used, for example, to determine if a 
called procedure has returned. 
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CONDITIONAL PREDICATES 

1. if 

if conditional expression: request 

if conditional expression: {request list) 

The request or request list is executed if the conditional 
expression is true. The expression must be of the form: 

expression operator expression 

where operator can be <« , <, =, >, or >«. 

Example: 

if a < b: let p = addr (a) 

This predicate is most useful in a break request list where it 
can be used to cause a conditional halt. For example, 

before: if z ''^ "10"b: halt 

causes the program to stop only when z "10"b. 

2. while, wl 

while conditional expression: request 

while conditional expression: (request list) 

The request or request list is executed repeatedly as long as the 
conditional expression is true. 

Example : 

while p""= null: (value p -> r.val; let p - p -> r.next) 
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Svaluation o£ Expressions 

Allowable expressions include simple scalar variables, constants, 

and probe builtin functions. The sum and difference of computational 

(arithmetic and string) values can also be used. 



Variables can be simple identifiers, subscripted references, 
structure qualified references, and locator qualified references. 
Subscripts are also expressions.. Locators must be offsets, pointer 
variables, or constants. 



Examples : 

running_total 
salaries (p -> i - 2) 
a.b(2) .c(3) 
a .b .c (2 , 3) 
x.y -> var 



Constants can be arithmetic, string, bit, and pointer. 
Arithmetic constants can be either decimal or binary, fixed or 
floating point, real or complex. Also, octal numbers are permitted as 
abbreviations for binary integers (e.g., 12o = 10). 



Examples : 

-123 

10b 

45.37 

4.73el0 

2.1-0,3i 

12345670O 



Character and bit strings without repetition factors are allowed. 
Character strings can include newline characters. Octal strings can 
be used in place of bit strings (e.g., "123"o = "001010011 "b) . 



Examples : 
"abc" 

"quote" " instr ing " 

"1010"b 

"01234567"o 
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A pointer constant is of the form: 



segment_number 1 word_of f set ( bi t_of f set) 



where the segment_number and word__offset must be in octal. The 
bit^offset is optional but if given must be in decimal. The pointer 
constant can be used as a locator. 



i?v am Ti^ cac • 

21415764 
23217413(9) 



Four builtin functions are provided by probe: addr, null, octal, 
and substr. The function of addr and null is the same as in PL/I: 
addr takes one argument and returns a pointer to its argument; null, 
taking no arguments, returns a null pointer. The function octal acts 
very much like the PL/I unspec builtin function in that it treats its 
argument as a bit string of the same length as the raw data value and 
can be used in a similar manner as a pseudo-variable. However, when 
used in the value request, the value is displayed in octal. Data 
items not occupying a multiple of three bits are padded on the right. 
The substr builtin function may be used as a function or 
pseudo-variable. It takes two or three arguments. The first argument 
must be a character or bit string or a reference to the octal builtin 
function; the second and optional third arguments give the offset and 
length of the desired substring as with the PL/I substr builtin 
function. 



Note 

These builtin functions cannot be used if a program variable of 
the same name appears in the block being referenced. (For example, if 
X and octal are arrays in the same block, then octal (x(2)) becomes a 
reference to the variable octal, not the probe builtin). 
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Examples : 

For the following examples, assume that p is declared as an 
aligned pointer, i as fixed binary initial(-2), and cs as character(8) 
initial ( "abcdefgh" ) . 

value addr (i) displays the address of i 

let p = null sets the pointer, p, to null 

value octal (i) displays the storage containing i in 

octal, giving: 777777777776 

value substr (cs, 2, 3) displays "bed" 

let substr (cs, 4, 1)="" sets cs to "abc fgh" 

Label References 

A label identifies a source program statement and can be a label 
variable or constant, a line number in source-listing format, or one 
of the following special statement designators: 

$c designates the "current statement" 

$b designates the statement on which the most recent break- 

occurred 

$ number designates a FORTRAN label 

An optional offset of the form " ,_s" is also allowed. 
Examples: 

label statement at label 

label^var statement to which l3bel_var is set 

17 statement on line 17 of program 

3-14,2 statement 2 on line 14 of include file 

3 

$b statement at which last break occurred 

$c,l statement after current statement 

$100 FORTRAN statement labeled 100 

Generally, a label can also be the name of a procedure, entry, or 
subroutine statement. 



Procedure References 
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A procedure_naine is an identifier representing an entry variable 
or constant. External reference names, representing entry points not 
declared in the current block, can be used. 



Evaluation of Variable References 

When a variable is referenced in a request, probe first attempts 
to evaluate it by checking for an applicable declaration in the 
current block and, if necessary, in its parents. If no declaration is 
found, the list of builtin functions is searched. Finally, when the 
context allows a procedure name, a search is made following the user's 
search rules. 



The block in which a variable reference is resolved can be 

altered by the use request that sets the current block. For example, 
if "value var" displays the value of var in the current block, then 
"use -1; value var" displays the value of var at the previous level of 
recursion. An optional block specification is available for 
referencing variables in other blocks: 



variable [block] 



where block is the same as in the use request. The use of blocks in 
this manner does not alter the block pointer. 



A block specification can be used to qualify a variable reference 
in any context the variable could be used. However, a block 
specification on a label or entry constant is ignored unless the 
relative (-n) format is used and the label or entry is itself used in 
a block specification. In such a case, it is taken to mean the nth 
previous instance of the block designated by the label or entry; that 
is, " var [ sub[-2] ] " references var in the second previous invocation 
(third on the stack) of sub. 



Not To Be Reproduced A-58 F21 



Examples: 



var [-1] 

abc [other__blockl 
xyz[39] 



looks for the previous value of var 

looks in "other_block" for abc 

looks in the block that contains line 

39 for xyz 
looks in the block at level 4 for n.m 
looks in the procedure sub for q(2) 



n.mClevel 4] 
q(2) [sub] 
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Sample Debugging Sessions 

Two extensive examples are given on the following pages to 
illustrate both how probe requests are used and how to get useful 
debugging information out of them, the first example was devised 
principally to demonstrate the application of probe requests. A 
listing of the source of the program, test, is given on the next page. 
The program has been compiled with the -table control argument (line 
1) . The sample output follows with an exclamation point (I) denoting 
lines typed by the user. Unless otherwise indicated, line numbers 
referenced in the following paragraphs are from the sample output. 



The user first calls his program (line 5); noticing that it seems 
to be looping, he stops it by issuing the quit signal (line 6). After 
the user invokes probe (line 10), it responds by telling him that the 
internal function fun was executing line 38 when interrupted. Since 
the source pointer was automatically set to that line, the source 
request (line 12) causes the current source statement to be displayed. 
A statement causing an error could be displayed in a similar manner. 



1 test: procedure; 
2 

3 declare. 
4 

5 ( i , j ) fixed binary , 

6 Is structure based (p) , 

7 2 num fixed binary, 

8 2b (n refer (s.num) ) float binary, 

9 p pointer, n fixed binary, 
10 sysprint file; 

11 
12 

13 n = 5; 

14 allocate s set (p) ; 
15 

16 do i = 1 to s.num; 

17 s.b(i) = fun (i, 1); 

18 end; 

19 out skip list (s.b); 
20 

21 do j * s.num to 1 by -1; 

22 s.b( j) = fun (-j , -1) ; 

23 end; 

24 put skip list(s.b); 
25 

26 return; 

27 
28 

29 fun: procedure (b, i) returns (float binary); 

30 

31 declare 
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32 (b, i) fixed binary; 

33 

34 if b = 0 

35 then return (1); 

36 else do; 

37 b = b - i; 

38 returnr- (2**b + fun (b, i) ) ; 

39 end; 
40 

41 end fun; 

42 

43 

44 end test; 
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1 I pll test -table 

2 PL/I 

3 r 1248 3.211 28.336 280 
4 

5 1 test 

6 i(quit) 

7 QUIT 

8 r 1250 5.371 6.702 52 level 2, 10 
9 

10 1 probe 

11 Condition quit raised at line 38 of fun. 



12 


I source 




13 




return {2**b 


14 


I stack 




15 


11 


command_processo r__ 


16 


10 


release_stack 


17 


9 


unc 1 a iined__s i g nal 


18 


8 


real__sdh_ 


19 


7 


r e t ur n_to_r i ng_0 


20 


6 


fun 


21 


5 


test 


22 


4 


command__processo r__ 


23 


3 


listen_ 


24 


2 


process_overseer__ 


25 . 


I 


user init admin 



qui t 



26 I . use level 5 

27 i source 

28 s.b(i) = fun (i, 1) ; 

29 i value s.num 

-1 n r 

31 i position "i = 1"; source 

3 2 do i - 1 to s.num; - 

33 i after: value i 

34 Break set after line 16 of test. 

35 I quit 

36 r 1252 1.375 16.394 354 level 2, 10 

37 

38 I release 

39 r 1252 .126 .922 19 
40 

41 1 test 

42 1 

43 1 

44 1 

45 1 

46 I (quit) 

47 QUIT 

48 r 1252 3.069 ,650 25 level 2, 12 
49 

50 1 release 

51 r 1253 .092 .937 20 
52 

53 i probe test 
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54 


1 


status 


55 




Break after line 16. 


56 




status after 16 


57 




Break after line 16: value i 


58 




reset at 16 


59 




Break reset after line 16 of test. 


60 


1 


position 34 


61 




source 


62 




if b =^ 0 


63 




then return ( 1 ) ; 


64 


1 


before: halt 


65 




Break set before line 34 of test« 


66 


1 


quit 


67 




r 1255 .781 12.356 333 


68 






69 


» 


test 


70 




Stopped before line 34 of fun. 


71 


f 


value b 


72 




1 


73 


1 


where 


74 




Current line is line 34 of test^ 


75 




Using level 6: fun. 


76 




Control at line 34 of fun. 


77 


I 


value i 


78 




1 


79 




c 


80 




Stopped before line 34 of fun. 


81 


1 


stack 5 


82 




8 break 


83 




7 fun 


84 




6 fun 


85 




5 test" 


86 




4 command_processo r_ 


87 


I 


value b 


88 




0 


89 


1 


value b[-l] 


90 




0 


91 


1 


value i 


92 




1 


93 


1 


symbol i 


94 




fixed binary{17,0) aligned parameter 


95 




Declared in fun. 


96 


1 


use test 


97 


1 


value i 


98 




0 


99 




reset 


100 




Break reset before line 34 of test. 


101 




quit 


102 




r 1307 4.870 64.788 1544 



The stack command is then used (line 14) to see in what order the 
procedures were called. The output shows that procedure test was 
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called from command level, and then called fun. While fun was 
executing, a quit signal was issued and established a new command 
level. 



The use request (line 26) sets the block pointer to the outermost 
block of procedure test, and the source pointer to the last statement 
executed in that block — the statement which invoked uhe function 
fun . 



The source request (line 27) is issued to display the current 
statement (as set above) to determine from which line of the program 
(17 or 27) fun was actually invoked.. 



Since the block pointer has also been set, the user can check the 
value of "s.num" with the value request (line 28) and ascertain that 
it is as desired. Since there is no new declaration of "s.num" within 
the procedure fun, the declaration made in the parent block, test, is 
known and the value of "s.num" could be displayed without changing the 
block pointer as would be necessary if there were a conflicting 
declaration. 



The user decides that it is worthwhile to trace the value of i. 
Rather than recompiling his program with a "put statement' added in a 
strategic location, probe allows him to set a break contair.ing a value 
request to accomplish the same thing. The user wants to s=t the break 
after the do statement on line 16 of the program and searches for it 
with the position request (line 31). The source request is used to 
verify that the correct line was found. The after request is used to 
actually set the break (line 33). The quit request (line 35) then 
causes probe to return command level. 



To abort the suspended program test, the user invokes the Multics 
release command (line 38). If he had done this just after issuing the 
quit signal, he could not have used probe to examine automatic 
variables inside the program or to determine where the program had 
been interrupted. 



The program is restarted (line 41) but now, after each execution 
of line 16, the break occurs and probe displays the value of i. 
Clearly, it is not being incremented as it should. Since this 
approach is not producing any useful information, the user aborts the 
program and tries to delete the break. The status request is used to 
tell what breaks have been set in the procedure test (line 54), and 
then (line 56) to see the probe request associated with that break. 
The break is then deleted with the reset request (line 58). If there 
had also been a "Break before 16", then the request "reset at 15" 
would have deleted both. 
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The user next decides to examine fun, so he sets a break that 
will halt every time fun is invoked (lines 60 through 64). Looking at 
the listing, he sees that the first statement in fun is on line 34, so 
he sets the source pointer to that statement with the position request 
and sets a break to halt the program. To accomplish the same thing, 
"before 34: halt" could have been used. 



The program is called (line 69) and then halts when the break 
before line 34 is reached. The user displays b and i (lines 71 and 
77), getting the values he expected. The where request is also used 
(line 73) to check on the current state of things. The continue 
request (line 79) restarts fun, which calls itself recursively and 
stops again. The stack request (line 81, showing the last five 
frames) verifies that fact. The user displays the b in the current 
instance of fun (line 87, at level 7) and in the previous one (line 
89, at level 6). Mistakenly expecting the b's at different levels to 
be different, he gets suspicious. The variable i has the value 
expected (line 91), but the symbol command (line 93) shows that it is 
the wrong instance of i — the parameter to fun, not the loop index. 
To get the correct instance, 'he must look in the frame belonging to 
the procedure test (line 96) and display that i (line 97). This i has 
been set to 0. The user then realizes his error. The function is 
modifying its argument (the loop index i) on line 37 (line 94). When 
the user has finished debugging the program-, the reset request (line 
99) is used to delete 'the currently active break (the one that just 
occurred) , and the- program is aborted with the quit request (line 
101) . 



The preceding example was constructed to give a user a feeling 
for applying probe requests. The following example is taken from an 
actual debugging session using probe and illustrates several 
additional techniques available to the user. 



The program of interest is a subroutine, sort_strings , that is 
supposed to sort a character array of arbitrary dimension; the array 
is passed as an argument to the subroutine. Since very large strings 
are being compared, it would be time consuming to exchange the strings 
themselves. Therefore, an array of pointers to the strings (actually, 
the indices of the strings in the original array) is first sorted by a 
simple bubble sort, and the strings moved afterwards into the correct 
order. There are (at least) two bugs in the program as it appears in 
the listing. The next two paragraphs further describe the algorithm 
intended . 



A bubble sort involves making repeated passes over an input 
array, comparing adjacent pairs of values, and interchanging them as 
necessary. This moves the larger (smaller) values toward the end of 
the array. The sort only covers that portion of the array that is out 
of order (i.e., up to the element where the final exchange took place 
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on the previous pass -- all elements following this point are clearly 
correctly arranged) . The example below illustrates how a bubble sort 
works in one case. {The hyphen delimits the end of the search.) 



Original First Pass Second Pass Third Pass 



d a a - 

a c b a 

c -> b -> - -> b 

b - c c 

e d d d 

- e e e 



In the sort_strings subroutine (see source listing below) , "k" 
determines the last element of the array needing to be sorted. 
Sorting continues until no exchanges occurred during the last pass 
(i.e., until the test, k 1, fails). The "order" array contains the 
indices that are actually sorted. 



The reordering method used is to scan for unordered items and 
then move the entire chain (a replaces b; b replaces c; and c replaces 
a) containing the element. For example: 



Initial Ordering Desired Ordering Movements 



1 e 3a temp <- 1 (e) temp <- 2 (d) 

2 d 4 b 1 <- 3 (a) 2 <- 4 (b) 

3 a 5 c 3 <- 5 (c) 4 <- temp 
4b 2d 5 <- temp 

5 c 1 e 



All elements that have been moved into the correct location are 
flagged as having been moved by setting their order values to -1. 

Source listings of the program and subroutine, named testss and 
so rt_^str ings respectively, are given below. 



1 testss: procedure; 



2 

3 /* test caller for so rt__str ings */ 

4 

5 declare 
6 

7 i fixed binary, sysprint file, 

3 sort_strings entry (character (256) varying dimension(* 

9 array (6) character ( 256 ) varying initial 
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10 ( "probe", "hello", "xray", "nice", "def" , "abc" 

\c); 

11 
12 

13 call sort__strings (array); 

14 do i = 1 to 6; 

15 put list (array (i)); 

16 put skip; 

17 end; 
18 

19 end testss; 



\c do; 
\c) = t; 



1 sort__str ings : procedure (strings); 
2 

3 declare 
4 

5 strings character (256) varying dimension(*) , 

6 order fixed binary dimension (hbound (strings, 1)), 

7 temp character ( 256) varying, 

8 (i, k, 1, t) fixed binary; 
9 

10 

11 /* initialize order array */ 

12 ■ 

13 do i = 1 to hbound (order, 1); 

14 order (i) = i; 

15 end; 
16 

17 /* perforin bubble sort */ 

18 

19 k, 1 = hbound (strings, 1); 

20 do while (k 1) ; 

21 do i = 2 to k; 

22 1 = i - 1; 

23 if strings (order (1)) > strings (order (i)) then 

24 t = order (1); order (1) - order (i); order (i 



25 k * 1; 

26 end; 

27 end; 

28 end; 
29 

30 /* move strings into above ordering */ 

31 

32 do i = 1 to hbound (strings, 1); 

33 if order (i) -1 then do; 

34 temp « strings (i); 
35 

36 /* follow chain 'til reach start again */ 

37 

38 do k =* i repeat 1 while (k -1); 

39 1 = o rder ( k) ; 

40 strings (k) = strings (1); 
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41 order (k) = -1; 

42 end; 

43 strings (1) = temp; 

44 end; 

45 end; 
46 

47 

48 end so rt_st rings; 

The debugging session begins below. Again, an exclamation point 
i) indicates lines typed by the user. 

1 i testss 

2 i(quit) 

3 QUIT 

4 r 736 6.068 0.132 9 level 2, 10 

5 

6 i probe 

7 Condition quit raised at line 21 of so rt__str i ngs . 

8 i source 

9 do i - 2 to k; 

10 I value k 

11 1 

12 I value 1 

13 1 



First the program testss, used to test the sort_strings 
subroutine, is called from command level (line 1). When no output is 
produced, the program is aborted by issuing a quit signal, and probe 
is invoked to determine where the program was looping (line 6). 

When probe is entered, it responds by giving the procedure and 
line where execution was interrupted. The source pointer is set by 
default to that line, so that the source request (line 8) may be used 
to display the text of the statement. The output does not indicate 
whether the infinite loop is occurring in the inner (do i = 2 to k) or 
outer (do while (k <= 1)) loop. The value of k (line 11) is 1, which 
implies that the inner loop is not being entered; the value of 1 (line 
13) is also 1 explaining why the outer loop never terminates. 



An examination of the program shows that k and 1 could take on 
these values if elements 1 and 2 are exchanged on a pass with k = 2; 
on subsequent passes, no exchanges are made (as the inner loop is not 
entered) , and the termination condition is never met. What is needed 
is to force 1 to be less than k on all passes unless an exchange 
actually occurs. This can be done by setting 1^-1 before attempting 
the inner loop. 
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14 


! 


before: let 1 = -1 


15 




Break set before line 21 of sort_: 


16 


1 


qui t 


17 




r 737 1.217 3.562 97 level 2, 10 


18 






19 


1 


start 


20 






21 




def 


22 




hello 


23 




probe 


24 




abc 


25 




xray 


26 




r 737 0.359 0.182 0 



The probe command can be used to modify the value of variables 
either interactively or as part of a break request list. In the 
latter case, the change is made every time the program is executed. A 
breakpoint is set before the current statement (line 21 of the program 
— the inner loop) to set the value of.l to -1 with the before request 
(line 14). The quit request (line 16) causes a return to command 
level, and the Multics start command (line 19) restarts the program 
from where it was interrupted. This time output is generated. 
However, the strings are not being sorted correctly. 



27 I probe so rt__stri ngs 

28 I position "i = 1"; source 

29 do i = 1 to hbound (order, 1) ; 

30 ! position "i = l";source 

31 do i = 1 to hbound (strings , 1); 

32 I before 

33 Break set before line 32 of so rt_str ings . 

34 ! quit 

35 r 738 0.218 0.002 14 
36 

37 I testss 

38 Stopped before line 32 of so rt_strings . 

39 I symbol order 

40 fixed binary(17,0) aligned automatic dimension(6) 

41 Declared in so rt_str ings . 

42 I value order(l:6) 

43 6 

44 5 

45 2 

46 4 

47 1 

48 3 



One way to determine whether it is the sorting or ordering 

section of the program that is functioning incorrectly, is to stop the 
program before the ordering section and look at its input, the array 
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"ordeTo" The position request (line 28) is an attempt to locate the 
desired statement, but the source request (line 28), used to check 
that the correct line has been found, shows that the wrong one was 
found. The process is repeated (line 30), and the source pointer set 
to the correct line. A break is set (line 32) to cause the program to 
"halt" at that statement and enter probe. The driving program is 
begun once again (line 37), and sort_strings halts at the desired 
location. The symbol request (line 39) is used to check that the 
correct dimensions are being received for the array order. The value 
request (line 42) is used to display order(l), order(6). It can 

be seen that these are the correct values ("abc", in position 6, is to 
be moved to position 1, etc.). 



49 ! position 39; source 

50 1 = order (k) 

51 I after: (value k; value 1) 

52 Break set after line 39 of sort_strings 

53 I continue 

54 1 

55 6 

56 6 

57 3 

58 3 

59 2 

60 2 

61 5 

62 5 

63 1 

64 1 

65 -1 

66 4 

67 4 

68 4 

69 -1 

70 nice 

71 def 

72 hello 

73 probe 
7 4 abc 

75 xray 

76 r 740 0.602 0.000 0 



It appears that the sorting code is working properly (with the 
patch in it). Therefore, the reordering of the array is failing for 
some other reason. The user then begins to trace the exchanges that 
are made. A break is set (lines 49 and 51) to display the values of k 
(the element to which the string is to be moved) and 1 (the element 
from which the string is to be moved) as the program is running. As 
stated previously, the effect of recompiling the program with a put 
statement added can be duplicated in this manner. The break is set 
after the line where both values have been determined for the 
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exchange. The 'continue request (line 53) restarts the program from 
where it was suspended by the break. 



The output shows that extra exchanges are taking place. When k ~ 
5, the next element on the chain is the first element (1 = 1) , and the 
fifth element should therefore be replaced by the copy of the first 
value stored in "temp." it should not be replaced by the current 
first element (the old element 6, "abc"). Nor should the program 
continue to move the undefined element -1 into element 1. 



77 1 probe sort_strings 

78 i reset at 39 

79 Break reset after line 39 of sort_strings . 

80 ! before 39: if order(k) = i: ( 

81 ! let strings(k) = temp 

82 I let order(k) = -1 

83 1 goto 42 

84 i . ) 

85 Break set before line 39 of so rt_str i ngs . 

86 I auit 

87 r 742 0.280 0.966 56 



For the program to work properly, the movement through the chain 
must stop when the next element is the first (i.e., when order (k) = 
i) . The saved value of the first (temp) should then be copied into 
the current element (strings(k) ) , and the search for additional 
unreordered elements continued. If the user were to recompile the 
program, the following code should achieve the desired effect. 



if order (i) -1 then do; 
temp = strings ( i) ; 

do k = i repeat 1 while (order (k) i) ; 
1 - order (k) ; 
strings (k) = strings (1); 
order (k) = -1 ; 

end; 

strings (k) = temp; 
order (k) = -1; 

end; 



This approach may be checked before recompilation by making a 
slightly more elaborate patch than the one made previously. The probe 
command may be used to place a check for the correct terminating 
condition as the first thing in the loop on k and, if the condition is 
met, cause strings(k) to be set and the loop exited. First the break 
(containing the two value requests) previously set after the statement 
(line 78) is reset. Then a break, containing several requests and 
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extending across line boundaries, is set (lines 80 through 84) before 
the statement on line 39 of the program. 



88 


i testss 




89 


Stopped before line 32 


of sort strings. 


90 


i reset 




91 


Break reset before line 


3 2 of so rt__st rings . 


92 


I continue 




93 


abc 




94 


def 




95 


hello 




96 


nice 




97 
98 


probe 
xray 




99 


r 743 0.357 1.582 42 




100 






101 


i probe so rt__str ings 




102 


I status 




103 


Break before line 39. 




104 


Break before line 21. 




105 


I status at 21 




106 


Break before line 21: 


let 1 = -1 


107 


! r»i 111- 




108 


r 744 0.184 1.146 72 





The program is run once again (line 38), and the break sat 
between the two sections is encountered again. As it is no longer of 
any use, the reset request (line 90), assuming the default of the last 
break encountered, is used to delete the break. The continue request 
(line 92) resumes the execution' of the program. This time it works! 



The. probe command is invoked once again. This time the status 
request is used to recall the breaks set, and, hence, the changes to 
be made to the program. Two forms of the status request are used. 
Just "status" (line 102) gives a list of all breaks set in the 
program; "status at line_number" (line 105) gives the text of the 
associated break request list. The user can now edit and recompile 
the program and expect it to work correctly. The remaining breaks 
need not be reset, because a recompilation has the same effect. 
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Terminology 

active - a procedure is said to be active if its execution is 
ongoing or suspended by an error, quit signal, breakpoint, 
or calle An active procedure should be distinguished from 
one that has never been run, has completed execution, or has 
been interrupted and aborted by a Multics release command. 



automatic storage - a storage class for which space is allocated 
dynamically in a stack frame upon block invocation. As a 
result, variables of this class only have storage assigned 
to them, and hence a legitimate address and value, when the 
block in which they are declared has an active invocation. 
PL/I variables, by default, belong to this class. FORTRAN 
variables must appear in an "automatic" statement in order 
to belong to this class. 



block - corresponds to a PL/l' procedure or begin block or FORTRAN 
program or subroutine, and identifies a particular group of 
variable declarations. 



breakpoint - a point at which program execution is temporarily 
interrupted and probe requests executed. 



invocation - when a procedure -is called recursively, it will 
appear on the stack two or more times, and will have storage 
allocated for it the same number of times. Each instance of 
the procedure on the stack is considered a separate and 
distinguishable invocation of the block. The values of 
automatic variables can be different in different 
invocations of the same block. The most recent invocation 
is the topmost in stack trace.. 



level number - an integer used by probe to uniquely designate 
each block invocation (i.e., each entry in a stack trace). 
Level one is the first (least recent) procedure invoked. 
Level number is not necessarily the same as either of the 
numbers given after the word "level" in a ready message. 
The first of this pair gives the count of command levels in 
effect and gives the value n+1, where n is the number of 
programs (or groups of programs) whose execution has been 
suspended, the second gives the number of stack frames in 
existence and since the probe stack includes quick blocks, 
this number is less than or equal to the level number of the 
last command level in the stack trace. 
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quick block - internal procedures and begin blocks that satisfy 
certain requirements (e.g., are not called recursively, do 
not contain on, signal, or revert statements, etc.) have 
their automatic storage allocated by the blocks that call 
them. Hence, they do not actually have their own stack 
frames, but share the one of the caller. Certain system 
commands, such as trace_stack, ignore these blocks. The 
probe command, however, includes them in a stack trace, and 
treats them as if they were the same as any other blocks. 
The quickness of a block may be determined from a program 
listing containing information about the storage requirement 
of the program (produced with the -symbols, -map, or -list 
control arguments) . For example, procedure "quick" shares 
stack frame of external procedure "main". 



stack - if a procedure A calls another procedure 3, then the 
execution of A is suspended until B returns. If B in turn 
calls C, then this is an ordered list of procedure or 
subroutine calls indicating which program called which other 
program, and which will return to which. This ordered list 
is called the "stack". In probe, a crace of the stack may 
be displayed by use of the stack request. The list is given 
in top-down fashion v;ith the most recently called procedure 
listed first: 



The numbers are level numbers. 



stack frame - when a block is invoked (that is, a procedure is 
called or a begin block is entered) , storage is allocated 
for its automatic variables. The area allocated is called a 
stack frame and logically corresponds to each entry in the 
stack . 



static storage ~ a storage class for which space is allocated 
once per process, effectively at the time the procedure is 
first referenced. As a result, variables of this class 
always have a legitimate address and value. Regular FORTRAN 
variables, and those in a common block, have static storage. 
PL/I variables must be explicitly declared. 

support procedure - a system utility routine that provides 

runtime support for other procedures (e.g., the procedure 

that allocates storage as requested by a PL/I allocate 
statement) . 



3 
2 



C 
B 
A 



1 



Not To 3e Reproduced 



A-7 3 



F21 



probe , pb 



Summary of Requests 



after 

before 

call 

execute 

goto 

halt 

if 

let 

mode 

pause 

position 

qui t 

reset 

source 

stack 

status 

step 

symbol 

use 

value 

where 

wh il e 



a 
b 

cl 



e 

g 

h 

( none) 
1 

( none) 

pa 
ps 

q 

r 

sc 
sk 

St 

s 

sb 

u 

V 

wh 
wl 



Set a break after a statement. 
Set a break before a statement. 
Call an external procedure. 
Return from probe* 
Execute a Multics command. 
Transfer to a statement. 
Stop the program. 

Execute commands if condition is true. 
Assign a value to a variable. 
Turn brief message mode on or off. 
Stop a program once. 

Examine a specified statement or locate 
a string in the program. 

Return to command level. 

Delete one or more breaks. 

Display source statements. 

Trace the stack. 

Display information about breaks. 

Advance one statement and halt. 

Display the attributes of a variable. 

Examine the block specified. 

Display the value of a variable. 

Display the value of probe pointers. 

Execute commands while condition is 
true . 
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de on or 

pause 

position 
prog ram . 

qui t 

reset 

source 

stack 

status 

step 

symbol 

use 

val ue 

where 

wh i 1 e wl 



off. 

pa -Stop a program once, 

ps Examine a specified statement or locate a string in the 



q 

r 

sc 

sk 

St 

s 

sb 

u 

wh 



Return to command level. 
Delete one or more breaks. 
Display source statements. 
Trace the stack. 

Display information about breaks. 
Advance one statement and halt. 

Display the attributes of a variable. 
Examine the block specified. 
Display the value of a variable. 
Display the value of probe pointers. 



Execute commands while condition is true 
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Name: profile 

The profile command is a debugging tool used in conjunction with 
the -profile (-pf) control argument of the pll, fortran, and cobol 
commands. The profile command prints information about the execution 
of each statement in the PL/I, COBOL, or FORTRAN program. 



The --profile control argument causes the com.pil9r to generate an 
internal static table containing an entry for each statement in the 
source program; the table entry contains information about the 
statement as well as a counter that starts out at zero. The counter 
associated with a statement is increased by one each time the 
statement is executed. The profile command prints and resets these 
counters. 



Usage 

profile paths { -control_args} 



wh ere: 

1. paths 

are the pathnames or reference names of programs whose 
counters are to be printed or reset. 

2. control_args 

are selected from the following list. Control arguments 
apply to all programs whose names appear in the command 
line. 

-print, -pr 

prints the following information for each statement in the 
specified programs: 

1. line number 

2. statement number, if greater than 1 

3. number of times the statement has been executed 

4. cost of executing the statement measured in number of 
instructions executed online plus the number of PL/I 
operators invoked. Each instruction and each 
operator invocation count as only one unit. 

5. the names of all the PL/I operators used by this 
statement 

6. total cost for all statements is printed at the end 
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-brief, -bf 

omits from the statement list statements that have never 
been executed. 

-long, -Ig 

includes in the statement list statements that have never 
been executed. 

-reset, -rs 

causes profile to reset to zero all counters associated 
with the specified program. 



Note 

If no control arguments are given, the default control arguments 

are -print and -brief. 



Example 

The PL/I program shown below counts the number of occurrences of 
one string in another string. It was compiled with the -profile 
control argijment and executed once. Notice that line number and 
statement number (LINE and ST, respectively) of the statement in the 
then clause is the same as the line number and statement number of the 
if statement itself. 



The source code for the program is: 



1 example: proc{sl,s2); 
2 

3 declare (sl,s2) char(*), 

4 (i,k) fixed bin, 

5 ioa_ options (variaicle); 
6 

7 k = 0; 

8 do i = 1 to length(sl) - length{s2); 

9 if substr ( si , i ,leng th( s2) ) = s2 

10 then k = k + 1; 

11 end; 
12 

13 call ioa_(""d" ,k) ; 

14 end example; 
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After executing the program once and invoking the profile command 
without any control arguments, the output is: 



LINE ST COUNT COST PROGRAM 

example 

7 11 

8 15 
S 8 24 

9 7 56 
9 11 

11 7 14 

13 1 13+1 (call__ext_out_desc) 

14 1 0+1 (return) 

TOTAL 114+2 
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Name : reset_external__var iables 

The r8set_extarnal__var iables command reinitializes system-managed 
variables to the values they had when they were allocated. 



Usage 

reset_external__variables names {-control_arg} 

where : 

1. names 

are the names of the external variables, separated by 
spaces, to be reinitialized. 

2. control_arg 

is -unlabel ed__common (or -uc) to indicate unlabeled (or 
block) common. 



Note 

A variable cannot be reset if the segment containing 
the initialization information is terminated after the 
variable is allocated. 
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Name ; r eso lve_l inkage__er ro r , rle 

The resolve_linkage__error command is invoked to satisfy the 
linkage fault after a process encounters a linkage error* The program 
locates the virtual entry specified as an argument and patches the 
linkage information of the process so that when the start command is 
issued the process continues as if the original linkage fault had 
located the specified virtual entry. 



Usage 

resolve__l inkage^error vir tual__entry 



where virtual^entry is a virtual entry specifier. 



Notes 

For an explanation of virtual entries, see the description of the 
cv_entry_ subroutine. 



Examples 

1 myprog 

Error: Linkage error by >udd>m>vv>myprog 1 123 
referencing subroutine$entr y 
Segment not found. 

r 1234 2.834 123.673 980 level 2, 26 

I rle mysub$mysub_entry 

r 1234 0.802 23.441 75 level 2, 26 

I start 

... myprog is running 
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Name ; run__cobol, rc 

The run__cobol command explicitly initiates execution of a COBOL 
run unit in a specified "main program". This command is not needed to 
execute COBOL object programs on Multics; it is used to simulate an 
environment in which traditional COBOL concepts may be easily defined. 
This command cannot be called recursively. 



Usage 

run_cobol name { -control__args} 



1 . name 

is the reference name or pathname of the "main program" in 
which execution is to be initiated. If a pathname is 
given, then the specified segment is initiated with a 
reference name identical to the entryname portion of the 
pathname. Otherwise, the search rules are used to locate 
the segment. If the name specified in the ?ROG~ID 
statement of the COBOL program (i.e., the entry point 
name) is different from the current reference name of the 
object segment, then the name specified here must be in 
the form A$3 where A is the pathname or reference name of 
the segment and B is the PROG-ID as defined in the 
IDENTIFICATION DIVISION of the source program, 

2. control__args 

can be chosen from the following: 

-cobol_swi tch- N, -cs N 

sets one or more of the eight COBOL-defined "external 
switches" on, where N is a number from 1 to 8 (or a series 
of numbers separated by spaces) that corresponds to the 
numbered external switch. At the outset of the run unit, 
the default setting of these external switches is off. 
(The eight external switches are defined in the Multics 
COBOL Reference Manual , Order No.lAS44.) 

-no__stop_run , -nsr 

avoids establishment of a handler for the stop__run 
condition. (See "Notes" below.) 

-sort__dir path, -sd path 

specifies the directory to be used during execution of 
this run unit for temporary sort work files. If this 
control argument is not specified, the process directory 
is assumed. 

-sort_f ile__si ze N, -sfs N 

is the floating point representation of the estimated 
average size in characters of the files to be sorted 
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during execution of this run unit. This information is 
used to optimize sorting. If not specified le6 is assumed 
(i.e., one million characters). 



Notes 

This command enables the user to explicitly define and start 
execution of a COBOL run unit. A run unit is either explicitly 
started by the execution of the run__cobol command or implicitly 
started by the execution of a COBOL object program either by 
invocation from command level or from a call by another program 
written in COBOL or another language. A run unit is stopped either by 
the execution of the STOP RUN statement in a COBOL object program or 
by invocation of the stop_cobol__run command. For the duration of time 
after a run unit is started and before it is stopped, it is said to be 
active. All COBOL programs executed while a run unit is active are 
considered part of that run unit. 



A run unit is a subset of a Multics process; it is stopped when 
the process is ended. Also, when all programs contained in a run unit 
are cancelled, the run unit is stopped (refer to the 
cancel_cobol__prog ram command) . Only one run unit niay be active at any 
given time in a process; thus, the run_cobol command cannot be invoked 
recursively. Additionally, if a run unit has been started implicitly 
(as described above), the run_cobol command may not be used until that 
run unit has been stopped; i.e., the run__cobol command does not 
terminate a currently active run unit. 



The explicit creation of a run unit with the run_cobol command 
performs the following functions: 



1. Establishment of a "main program", i.e., a program from 
which control does not return to the caller. The EXIT 
PROGRAxM statements, when encountered in such a program, have 
no effect, as required in the COBOL definition. An 
implicitly started run unit has no "main program". The EXIT 
PROGRAM statement in all programs contained in such a run 
unit always causes control to be returned to the caller, 
even if the caller is a system program, e.g., the command 
process© r . 

2. Setting of the COBOL external switches. These switches are 
set to • off unless otherwise specified by the -cobol_swi tch 
control argument. 

3. User control of the action taken when a STOP RUN statement 
is executed in a COBOL object program. The action normally 
taken for STOP RUN is cancellation of all programs in the 
run unit, closing any files left open. After this has been 
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done, the data associated with any of the programs is no 
longer available. Thus in a debugging environment, it may 
be useful to redefine the action taken for STOP RUN. When 
the run unit is explicitly initiated with the run___cobol 
command, the STOP RUN statement causes the signalling of the 
stop_run condition for which a handler is established that 
performs the normal action described above. If the 
-no_stop__run control argument is specified, the handler is 
not established, thus allowing the user to handle the signal 
himself using other Multics commands. If the user has not 
provided a handler himself for stop__run and specifies the 
-no_stop__run control argument, an unclaimed signal results. 



The name given in the run__cobol command need not be a COBOL 

object program. It may be a program produced by any language compiler 

that provides a meaningful interface, with COBOL programs (e.g., PL/I, 
FORTRAN) . 



Refer to the following related commands: 

display_cobol_run__unit , dcr 
stop__cobol__run , scr 
cancel__cobol_program , ccp 
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Name ; set fortran common, sfc 



The set_fortran__coramon command allocates and initializes all 
FORTRAN common blocks referenced by the specified FORTRAN object 
segments. The maximum declared length of a common block (of all those 
found in the list of FORTRAN object segments) is used for the 
allocation and initialization. This command can therefore be used to 
guarantee that the correct common block storage is allocated and 
initialized prior to a FORTRAN run. (If the user left it to the 
dynamic linker, the first reference to the common block would cause it 
to be allocated and initialized as declared in the referencing 
program. This program might not include the necessary initialization 
information.) The set__f ortran__common command can also be used to 
reinitialize the common blocks referenced by the specified object 
segments, although it will not reinitialize any local storage such as 
static or automatic variables. 



Usage 

setj_f o rtran_commcn paths { -control^arg } 
where: 

1. paths 

are the pathnames of the FORTRAN object segments whose 
common blocks are to be allocated and ( re) ini tial ized . 

2. control__arg 

can be -long (-Ig) indicating that warning messages are to 

be printed. Normally, all warning messages are 

suppressed. Warnings are printed if the common block is 
already allocated with a smaller size. 



Notes 

A FORTRAN object segment is either a segment created by one of 
the Multics FORTRAN compilers or is a segment created by the binder 
and contains at least one component that was created by one of the 
Multics FORTRAN compilers. 



Only common storage is affected by this command. Local variables 
are not ( re) initial ized . 



Common blocks without data initialization information are set to 
binary zeros. 
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If the common block is already allocated, its contents are 
reinitialized and the prior contents are lost. 



A warning is always printed if different initialization values 
are encountered in the set of specified object segments. 
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Name ; set__system__sto rage 

The set__system_storage command establishes an area as the storage 
region in which normal system allocations are performed. 



Usage 

set_system_storage {virtual_ptr -control_arg} 



where : 

1. virtual^ptr 

is a virtual pointer to an initialized area. The syntax 
of virtual pointers is described in the cv__ptr_ subroutine 
description. This argument must be specified only if the 
-system control argument is not supplied. 

2. control_arg 

is -system to specify the area used for linkage sections. 
This control argument must be specified only if 
virtual_ptr is not specified. 



Notes 

To initialize or create an area, refer to the description of the 
create area command. 



The area, must be set up as either zero_on_free or zero__on_alloc , 



It is recommended that the area specified be extensible. 



Examples 

The command line: 

set_system__storage free_$fr9e_ 

places objects in the segment whose reference name is free__ at the 
offset whose entry point name is free_. 
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The command line: 

set__system_storage my_seg$ 

uses the segment whose reference name is my__seg . The area is assumed 
to be at an offset of 0 in the segment. The segment must already 
exist with the reference name my___seg and must be initialized as an 
area , 



The command line: 

set_system__sto rage my^seg 

uses the segment whose (relative) pathname is my__seg . The segment 
must already exist. 
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Name ; set__user__storage 

The set__user_storage command establishes an area as the storage 
region in which normal user allocations are performed. These 
allocations include FORTRAN common blocks and PL/I external variables 
whose names do not contain dollar signs. 



Usage 

set__user_storage {virtual_ptr -control_arg } 



where : 

1. virtual^ptr 

is a virtual pointer to an initialized area. The syntax 
of virtual pointers is described in the cv_ptr_ subroutine 
description. This argument must be specified only if the 
-system control argument is not specified. 

2. control__arg 

is -system to specify the area used for linkage sections. 
This control argument must be specified only if 
virtual ptr is not specified. 



Notes 

To initialize or create an area, refer to the description of the 
create area command. 



The area must be set up as either zero__on__f ree or zero_on__alloc . 



It is recommended that the area specified be extensible. 



Examples 

The command line: 

set_user_storage free_$free__ 

places objects in the segment whose reference name is free_ at the 
offset whose entry point- name is free__. 
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The command line: 

set_user_storage my_seg$ 

uses the segment whose reference name is my__seg. The area is assumed 
to be at an offset of 0 in the segment. The segment must already 
exist with the reference name my_seg and must be initialized as an 
ar ea . 



The command line: 

set_user__sto rag e my__seg 

uses the segment whose (relative) pathname is my__seg . The segment 
must already exist. 
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Name ; stop cobol_run, scr 



The stop__cobol__run command causes the termination of the current 
COBOL run unit. Refer to the run_cobol command for information 
concerning the run unit and the COBOL runtime environment. 



Usage 

stop__cobol__run { -control__arg } 



where the control__arg may be - retain__data or -retd to leave the data 
segments associated with the programs composing the run unit intact 
for debugging purposes. (See "Notes" below.) 



Notes 

The results of the stop_cobol__run command and the execution of 
the STOP RUN statement from within a COBOL program are identical. 
Stopping the run unit consists of cleaning up all files that have been 
opened during the execution of the current run unit, and ensuring that 
the next time a program that was a component of this run unit is 
invoked, its data is in its initial state. 



To maintain the value of all data referenced in the run unit in 
its last used state, the -retain data control argument should be used. 



Refer to the related commands: 



display_cobol__run_unit , dcr 
cancel__cobol__program , ccp 
run cobol, rc 
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Name ; trace 

The trace command is a debugging tool that lets the user monitor 
all calls to a specified set of external procedures. The trace 
command modifies the standard Multics procedure call mechanism so that 
whenever control enters or leaves one of the procedures specified by 
the user, a debugging procedure is invoked. The user can request the 
following : 



1. Print the arguments at entry, exit, or both. 

2. Stop (by calling the command processor) at entry, exit, or 
both. 

3. Change the frequency with which tracing messages are printed 
(e.g., every 100 calls, after the 2000th call, only if the 
recursion depth is less than five, etc.) . 

4. Execute a Multics command line at entry, exit, or both. 

5. Meter the time spent in the various procedures being 
monitored. 



Use of the trace command is subject to the following 

restrictions: 



1. Only external procedures compiled by PL/I or FORTRAN can be 
traced . 

2. Ring 0 or gate entries cannot be traced. 

3. Incorrect execution results if the traced procedure looks 
back a fixed number of stack frames, e.g., cu_$arg__ptr 
cannot be traced. 

4. Only 100 procedures can be traced at one time. Up to 16 
locations can be watched at one time. 

5. The procedure being traced and the trace package itself must 
share the same combined linkage segment. 

6. A procedure in a bound segment can only be traced if its 
entry point is externally available. 



Usage 

trace {-control args} names 



Not To 3e Reproduced 



A-91 



F21 



trace 



where: 

1. names 

is a pathname or reference name,. The reference name or 
entry portion of a pathname is used in the trace table. 
(See "Notes" below.) 

2. control__args 

apply to the namej. arguments that follow, and, if 
applicable, change the current value in the trace control 
template (TCT) . (See "Notes" below.) Control arguments 
may be chosen from the following: 

-after N 

calls the command processor after calling the traced 
procedure every N times (initial valuel=lO: do not call). 

-argument N, -ag N 

prints the arguments every Nth time the procedure is 
entered (initial valuel=lO: do not print). 

-before N 

calls the command processor before calling the traced 
procedure every N times (initial valuel=lO: do not call). 

-brief, -bf 

prints a short form of the monitoring information. 

-depth N, -dh N 

monitors to the maximum recursion depth of N (initial 
valuel=lO: no limit). 

-every N, -ev N 

monitors every Nth call (initial valuel=ll). 

-execute STR, -ex STR 

executes the Multics command line specified by the string 
STR whenever the procedure is monitored (initial 
valuel-I"": no command). 

-first N, -ft N 

starts monitoring on the Nth call (initial valuel=!l), 

-govern STR, -gv STR 

limits/does not limit the recursion level for a procedure, 
where STR can be the string on or off (initial 
valuel = I of f ) . See "Recursion Limiting" below. 

-in 

prints the arguments only on entry (initial valuel= I yes) , 
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- inout 

prints the arguments on both entry and exit (initial 
value! = i no) . 

-io__switch STR, -is STR 

changes the switch for output to the switch specified by 
STR. (See "Changing Output Switch" below.) 

-last N, -It N 

stops monitoring after the Nth call (initial 
valuel=IS9993999S9) . 

-long, -Ig 

prints the long form of the monitoring information. (For 
use after the -brief control argument to restore the long 
f orm. ) 

-meter STR, -mt STR 

meters/does not meter the time spent in the procedure, 
where STR can be the string on or off (initial 
value!= « of f ) . See "Metering" below. 

-out 

prints the arguments only on exit (initial valuei=lno). 
-off entryname 

stops monitoring the specified procedure. The procedure 
remains in the trace table and calls continue to be 
counted. 



-on entryname 

resumes monitoring the specified procedure. This control 
argument is used after the -off control argument. 

-remove entryname, -rm entryname 

removes the specified procedure from the trace table. 
Tracing can be removed at any time. 

-reset entryname, -rs entryname 

sets the number of calls and recursion depth of the 
specified procedure to zero, 

-return__value STR, -rv STR 

prints/does not print the return value on exit, where STR 
can be the string on or off (initial valuel= I of f ) . This 
control argument assumes the entry is a function. 

-status * , -St * 

prints the procedures being monitored and their counters. 
(See "Notes" below.) 
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-status entryname, -st entryname 

prints the trace parameters and counters for the procedure 
specified by entryname. (See "Notes" below.) 

-stop_proc path, -sp path 

changes the procedure that is called for stop requests 
from the command processor to the procedure specified by 
path. To reset the stop procedure, issue this control 
argument with no path argument. 

-subtotal, -stt 

prints and does not clear the metering statistics. 

-template, -tp 

lists the trace control template. 



Notes 

The procedure whose pathname is given in the command line is added 
to the trace table with the tracing parameters from the trace control 
template (TCT) . If the procedure is already in the table, the 
counters are reset and the current parameters in TCT are used. 



For control arguments that affect procedures being traced, the 
argument is an entryname or an asterisk (*). If an entryname is used, 
the control ' argument applies to that procedure. If an asterisk is 
used, the control argument is applied to all entries in the trace 
table. All control arguments that affect the TCT must have a number 
argument (indicated by N above). 



Examples 

The command line: 

trace -ag 1 -inout test 
prints the arguments for test on entry and exit. 



The command line: 

trace -ag 2 -in -depth 6 test 

prints the arguments for test every second time test is entered up to 
a recursion depth of six, i.e., 2, 4, 6. 



The command line: 
trace -govern on test 
Mot To Be Reproduced A-94 F21 
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prints the argumants of test each time test is called with a new 
maximum recursion depth. The trace procedure calls the command 
processor every time the recursion depth is a multiple of 10. 



The command line: 
trace -st * -tp 

lists the procedures in the trace table and prints the values of the 
trace control template. 
Message Format 

The message printed when control enters a procedure can appear in 
any one of several formats, depending on the setting of the brief 
switch and the status of the calling procedure. If the calling 
procedure is unbound or occurs in a bound segment containing a 
bindmap, the message takes the form: 



Call 4.1 of alpha from beta!l27, ap = 204110746. 



This is the fourth call of procedure alpha, which is at recursion 
level 1. The call comes from location 127 in component beta, and the 
argument list is at 204 110746. If the procedure making the call is in 
a bound segment that does not contain a bindmap, the message takes the 
fo rm : 



Call 4.1 of alpha from bound_gammal 437 (beta), ap = 204110746. 



The name in parentheses may not always be available and may be omitted 
in some cases. If the user has requested the brief output mode, the 
message is shortened to: 



Call 4.1 of alpha. 



When tracing is requested for a procedure, the parameters for that 
entry are taken from the trace control template (TCT) . If the user 
does not alter the values in the TCT, the initial default values are 
used (see below). The initial values in the TCT specify that every 
call should be monitored. 
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Trace Control Template 

As mentioned earlier, the trace table entry holds a number of 
parameters for each procedure to be traced. The values of the 
parameters are determined by the contents of the TCT at the time the 
table entry is filled in. These parameters are used in conjunction 
with N (the number of calls to the traced procedure in this process) 
and R (the current recursion depth) to control when and how the 
procedure should be monitored. The execution count (N) is set to 0 
when tracing is first started and is incremented by 1 every time the 
traced procedure is called. The recursion depth (R) is set to 0 when 
tracing is first started and is incremented by 1 every time control 
enters the traced procedure and is decremented by 1 every time control 
leaves the traced procedure. 



Le t : 

D - the maximum recursion depth to be monitored (-depth) 
F = the number of the first call to be monitored (-first) 
L = the number of the last call to be monitored (-last) 
E « how often monitoring should occur (-every) 

B = the number of times the procedure is called before trace 

stops at entry to the traced procedure (-before) 
A = the number of times the procedure is called before trace 

stops at exit from the traced procedure (-after) 
AG = the number of times the procedure is called before trace 

prints the arguments of the traced procedure (-argument) 
I = a bit that is "l"b if the tracing procedure should print the 

arguments of the traced procedure when control goes into the 

traced procedure (-in) 
0 = a bit that is "l"b if the tracing procedure should print the 

arguments of the traced procedure when control goes out of 

the traced procedure (-out) 



A call is monitored and the tracing procedure is called if, and 
only if: 



F <= N L 
R <= D 

mod(N,E) = 0 



If AG 0 , mod(N,abs(AG) ) = 0, and I = "l"b, trace prints the 

values of the arguments (if any) being passed to the traced procedure. 
All of the arguments are listed when AG < 0 . If AG < 0 , the procedure 
is assumed to be a function and the value of the last argument is 
printed after the procedure returns. 
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If B 0 and niod(N,B) = 0, the monitoring procedure prints 

"Stop" and calls the command processor (or a user-set procedure if the 
-stop^proc control argument was used) . This call occurs before the 
procedure being traced has created its stack frame. 



After control leaves the traced procedure, trace prints a line of 
the form: 



Return N.R from alpha. 



'If AG "= 0 and mod (N , abs ( AG) ) = 0, then all of the arguments of 
the traced procedure are printed if 0 = "l"b; otherwise, if AG < 0, 
the value of the last argument (assumed to be the value of the 
function) is printed. 



Finally, trace calls the command processor. If the -stop_proc 
control argument was given, a procedure set by the user is called. 
This call occurs after the stack frame of the procedure being traced 
has been destroyed. 



Metering 

The trace command can be used to meter the execution of a 
specified set of procedures. If the metering feature is being used, 
trace does not call the debugging procedure when control enters a 
procedure being traced; instead, it determines the current time and 
the virtual CPU time used, and the number of page faults taken by the 
user's process before control enters and after control leaves the 
traced procedure. This information is used to compute the real time 
and CPU time used, and the number of page faults taken by the traced 
procedure on a local and global basis. The global CPU time is the 
time spent in the procedure including the time spent in any procedures 
that it calls. The local CPU time does not include the time spent in 
any traced procedure called by the procedure, but it does include time 
spent in called procedures that are not being traced. The local and 
global versions of real time and page faults are calculated in a 
similar manner. Metering is only done when the first, last, every, 
and depth tracing conditions are satisfied. 



The control argument: 



-meter on, -mt on 
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sets the metering switch in the TCT; any procedures added to the trace 
table or that have their table entries updated after this argument is 
used are metered. 



The control argument: 



m.eter off, -mt off 



turns off the metering switch in the TCT; any procedures currently 
being metered continue to be metered. 



The control argument: 



-total 



causes trace to print the metering statiistics of all procedures in tne 
trace table. The output gives the number of calls (#CALLS) , global 
CPU time (GCPU) , global real time (GREAL) , global page waits (GPWS' , 
local CPU time (LCPU) , local real time (LRSAL) , local page waiis 
(LPWS) , and the usage percentage (%USAGE) based on local CPU time, :f 
all the procedures being metered. The metering statistics are set co 
0 after they are printed. 



The control argument: 



-subtotal, -stt 



prints the same information as the -total control argument, but do is 
not clear the statistics. 
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Recursion Limiting 

The control argument: 



-govern on, -gv on 



sets a bit in the TCT that causes recursion limiting to be in effect 
for any procedure subsequently added to the trace table. When the 
governing feature is used, the depth control parameter is ignored and 
trace prints the call message only when the recursion depth of the 
traced procedure reaches a new, maximum depth. Each call message has 
a recursion depth one greater than the previous call message. in 
addition, trace calls the command processor (or a user-defined 
procedure if the -stop__proc control argument was used) whenever the 
recursion depth is a multiple of 10. Return messages are not printed. 
This feature enables the user to find and limit uncontrolled 
recursion; it can be very useful in finding the procedure(s) 
responsible for fatal process error. 



The control argument: 



-govern off, -gv off 



turns off the governing switch in the TCT; any procedure currently 
being governed continues to be governed. 



Watch Facility 

The trace command has an optional watch facility in which trace 
watches the contents of a set of previously specified memory cells. 
The cells are checked at every entry to and every exit from every 
traced procedure. As long as the values in the locations being 
watched remain the same, no action is taken and no tracing messages 
are printed. The tracing message is printed as soon as trace finds 
that any of the locations being watched has had its value changed. 
This can be found either at entry to or exit from the traced 
procedure. When any value changes, the tracing message is preceded by 
lines that give the new values of all of the locations that have 
changed, and the command processor (or a user-set procedure if the 
-stop_proc control argument was used) is called even if the A or B 
conditions are not met. When execution continues, the locations that 
have changed are watched with the new value being used in subsequent 
checks. This feature can be very useful in determining which of the 
user's procedures has incorrectly modified a word of storage. 
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The control argument: 



-watch STR, -wt STR 



causes all procedures being traced to watch for a change in the 
current contents of the memory word(s) specified by the string STR. 
This string, specifying the location,- can consist of a single address 
specification or a series of address specifications separated by 
blanks and surrounded by quotes. If an address specification does not 
contain a vertical bar (I), it is taken to be an octal number giving a 
location in the stack; otherwise, it is taken to be a segment number 
and offset in octal in the standard form, e.g., segment__number 1 off set . 



The control argument: 



-watch off, -wt off 



turns off the watch facility. 



The watch facility differs from other trace facilities in that 
there is a single table of locations being watched that is used by all 
procedures being traced. When the -watch control argument is 
processed, the new location(s) specified replace any locations 
currently in the watch table. There is no provision made for removing 
a single location from the watch table; the user must reissue a watch 
request that omits the location to be removed from the table. 



Command Execution 

The command execution facility of trace allows the user to 
specify a Multics command line to be executed whenever the trace 
debugging procedure is called. The trace procedure calls the command 
processor with the specified string after printing the tracing 
message, but before the stop request causes the command processor to 
be called. 
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The control argument: 



-execute string 



sets the execution string parameter in the TCT. Since string is a 
single argument, it must be enclosed in quotes if it contains any 
spaces. The execution parameter in the TCT is turned off if string 
has zero length {-execute "") . The following line: 



trace -ex time test 



causes 
cal led 



trace to execute the time command before and after test is 



Changing Output Switch 

All of the messages from the trace command that may b.e generated 
while actually monitoring procedures are normally written on the 
user i/o switch so that trace can conveniently be used with procedures 



that change the 
control argument 



attachment of the normal switch, user output. The 



-io switch 3TR 



causes trace to write furthe-r monitoring output on the switch 
specified by STR, which must already be attached and opened for 
str eam_output . 
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Name: trace__stack , ts 

The trace_^stack command prints a detailed explanation of the 
current process stack history in reverse order (most recent frame 
first) . For each stack frame, all available information about the 
procedure that established the frame (including, if possible, the 
source statement last executed), the arguments to that (the owning) 
procedure, and the condition handlers established in the frame are 
printed. For a description of stack frames, see "Multics Stack 
Segments" in Section! IV of the MPM Subsystem Writers' Guide, 



The trace__stack command is most useful after a fault or other 
error condition. If the command is invoked after such an error, the 
machine registers at the time of the fault are also printed, as well 
as an explanation of the fault. The source line in which it occurred 
can be given if the object segment is compiled with the -table option. 



Usage 

trace stack {-control args} 



where control__args can be selected from the following: 
-brief, -bf 

suppresses listing of arguments and handlers. This 
control argument cannot be specified if -long is also 
specified as a control argument. 

-long, -Ig 

prints octal dump of each stack frame. 

-depth N, -dh M 

dumps only N frames. 



Output Format 

When trace__stack is invoked, it first searches 
backward through the stack for a stack frame containing 
saved machine conditions as the result of a signalled 
condition. If such a frame is found, tracing proceeds 
backward from that point; otherwise, a comment is printed 
and tracing begins with the stack frame preceding 
trace stack. 



If a machine-conditions frame is found, trace__stack 
repeats the system error message describing the fault. 

Unless the -brief control argument is specified, 
trace__stack also prints the source line and faulting 
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instruction and a listing of the machine registers at the 
time the error occurred. 



The command then performs a backward trace of the 
stack, for N frames if the -depth N argument was 
specified, or else until the beginning of the stack is 
reached . 



For each stack frame, trace__stack prints the offset 
of the frame, the condition name if an error occurred in 
the frame, and the identification of the procedure that 
established the frame. If the procedure is a component of 
a bound segment, the bound segment name and the offset of 
the procedure within the bound segment are also printed. 



The trace_stack command then attempts to locate and 
print the source line associated with the last instruction 
executed in the procedure that owns the frame (that is, 
either a call forward or a l.ine that encountered an 
error) . The source line can be printed only if the 
procedure has a symbol table (that is, if it was compiled 
with the -table option) and if the source for the 
procedure is available in the user's working directory. 
If the source line cannot be printed, trace_stack prints a 
comment explaining why. 

Next, trace__stack prints the machine instruction last 
executed by the procedure that owns the current frame. If 
the machine instruction is a call to a PL/I operator, 
trace_stack also prints the name of the operator. If the 
instruction is a procedure call, trace_stack suppresses 
the octal printout of the machine instruction and prints 
the name of the procedure being called. 



Unless the -brief control argument is specified, 
trace stack lists the arguments supplied to the procedure 
that "owns the current frame and also lists any enabled 
condition, default, and clean-up handlers established in 
the frame. 



If the -long control argument is specified, 
trace__stack then prints an octal dump of the stack frame, 
with eight words per line. 



Not To Be Reproduced 



A-103 



F21 



trace stack, ts 



Example 

After a fault that reenters the user environment ?nd 
reaches command level, the user invokes the trace_stack 
command . 

For example, after quitting out of the list command, 
the following process history might appear: 



I list 
Segments=8 , Records=3 

rew 0 mailbox 

r w 
QUIT 

I trace stack 

quit Tn ipc_$block i 156 

(>system__l ibrary_l>bound__command_loop_l 156) 
Mo symbol table for ipc_ 
156 400010116100 cmpq pr4ll0 

Machine registers at time of fault 

pro (ap) 263! 4656 pll_operato rs__$operator_table! 162 

(external symbol in separate nonstand 

card 

text section) 



prl 


(ab) 


1031264 






scs 1 264 


pr2 


(bp) 


14 1 12200 






as_linkagel 12200 


pr3 


(bb) 


113 10 






tc datalO 


pr4 


dp) 


253 i 2250 






IBBBJGjFkPBWcNZ .area.l inker! 2250 












(internal staticlO for ipc ) 


pr5 


(lb) 


244 i 3614 






stack 413614 


pr6 


(sp) 


244 1 3500 






stack_4 13500 ( -> "kcpMbLH +0000000" 


pr7 


(sb) 


24410 






stack_4 1 0 


xO 


73 


xl 


0 


x2 


0 x3 600000 


x4 


0 


x5 


32 


x6 


3033 x7 4 



a 000000000000 q 000000000004 e 0 
Timer reg - 1746005, Ring alarm reg - 0 

SCU Data: 

4030 400270250011 000000000021 400270000000 000000672000 
000156000200 000154000700 002250370000 600044370120 

Connect Fault (21) 

At: 270 1156 ipc_1156 ( bound_command_loop_|l 56 ) 
On: cpu a (^0) 
Indicators: "bar 
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APU Status: xsf, sd-on, pt-on, fabs 
CU Status: rfi, its, fif 

Instruc tions : 

4036 002250 3700" 00 8pp4 2250 

4037 6 00044 3701 20 epp4 pr6|44,* 

Time stored: 08/02/77 1635.5 edt Tue (104541674361226602) 
Ring: 4 

Backward trace of stack from 24413500 



3500 quit ipc_$block 1 156 (bound__coramand_loop_| 156) 
No symbol table for ipc__ 
156 400010116100 cmpq pr4ll0 

ARG 1: 25315704 » BBBJGj FkPBWcNZ .area .1 inker I 5704 
ARG 2: 24413152 stack_4 13152 
ARG 3: 0 



2720 tty_$tty_get_line! 244 2 ( bound_iox_111546) 

No symbol table for tty_ 
call__ex t_out to ipc__$ block 

ARG 1: 25314320 I 3BBJG j FkFBWcNZ . a rea . 1 i nke r i 4 320 

(internal static! 154 for find_iocb) 
ARG 2: 24412660 s tack__4 1 2660 ( -> " f o stuff") 
ARG 3: 12S 
ARG 4: 0 
ARG 5: 0 



2400 listen__$listen_l 461 ■ (bound__command_loop_l 1325) 

No symbol table for listen_ 
call^ex t__out to iox_$get_l ine 
ARG 1: 

on "cleanup" call listen__l256 (bound_command_loop_l 1122) 



2100 process_overseer__$process__overseer__l 473 (bound__command__loop 

\c_i21433) 

No symbol table for process_over seer_ 
call_ext_out__desc to listen_$listen_ 

Argument list header invalid. 

on "any other" 

call "itandard_def aul t_handler_$standard_def aul t_handler_3 
(external symbol in separate nonstandard text section) 



2000 user__init_admin_$user__ini t_admin_l 36 (bound_command_loop_| 2 

\cl676) 

No symbol table for user__ini t_admin_ 
21676 700036670120 tsp4 pr7l36,* alm^call 

No arguments. 

End of trace. 
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r 1635 1.756 40.790 207 level 2, 9 



Not To 3e Reproduced 



A-106 



F21 



APPENDIX W 

Workshops W-1 

Workshop One W-1 

Workshop Two W-10 

Workshop Three W-1 3 



Workshops 
W-i 



WORKSHOP ONE 



A probe Workshop 



The best (perhaps the only) way of learning how to use the probe 
command is by using the command in actual debugging sessions. This 
workshop provides the experience of debugging a moderately complicated 
program. The program computes and prints out the elements of a 
Fibonacci series. An F series begins as 

0 1 1 2 3 5 8 13 21 34 55 ... 

An element of the series is calculated by adding the previous 2 
elements (for a Fibonacci series of degree 2). In the series shown 
above, the first two elements (0 and 1) are given as initial values 
and the remaining elements are then computed. 



Fibonacci series of higher degrees can also be defined by adding more 
elements to calculate the next in the series. For example, a series 
of degree 4 begins as 

0 0 0 112 4 8 15 2956 108 ... 

with the next element of the series calculated by adding the previous 
4 elements in the series. 



The program shown below reads two parameters from the terminal: Fdeg 
gives the number of the highest degree Fibonacci series to be 
computed; count gives the number of elements to be included in each 
series. For input of 

Fdeg=4, count-7; 

the first seven elements (excluding the assumed initial values) of the 
Fibonacci series of degrees 2, 3, and 4 are printed. 



Now, without further ado, here are the orogramsl There is one written 
in PL/I, and one written in FORTRAN. You can copy whichever of these 
programs you wish to debug from > udd>F19>Student_0i>f ib .pll (or 
.fortran) into your home directory. Note that the line numbers shown 
below are not actually a part of the so-irce segment. q 
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1 fib: proc; 
2 

3 del (sysin^ sysprint) file, 

4 Sfirst bit(l) int static init{"l"b), 

5 (Pdea, count, i) fixed bin, 

6 msg char(256) varying; 
7 

8 del linesize fixed bin, 

9 get_line_length_$ stream entry (char(*) , fixed bin(35)) 
10 " returns( fixed bin); 

11 

12 del cleanup condition; 

13 

14 /* Establish cleanup on unit to close files. */ 

15 /* Open input/output files, get output file line */ 

16 /* length to insure output lines fit on terminal, */ 
1 7 

18 on cleanup close file(sysin) , file (sysprint) ; 

19 open file(sysin) stream input; 

20 open file ( syspr int) stream output; 

21 linesize = get_line__length_$ stream ("sysprint", 0); 
22 

23 /* Initialize indicator of how many series should */ 

24 /* be output (Fdeg) and how many items should be */ 

25 /* output in each series (excluding assumed */ 

26 /* initial elements of each series) . */ 
27 

28 • Fdeg = 2; ' 

29 count - 10; 
30 

31 

32 /* Output brief instructions to the user, but */ 

33 /* only the first time fib invoked in each process*/ 
34 

35 if Sfirst then do; 

36 msg = 

37 "Enter Fdeg and/or count, followed by a character."; 

38 write f ile(syspr int) from(msg); 

39 msg = 

40 • "For example , 

41 Fdeg = 2, count=10;"; 

42 write f ile(sysprint) from(msg); 

43 msg = 

44 "These are the default values. To stop, enter 

45 Fdeg =1; 
46 

47 write file ( syspr int) from(msg) ; 

48 Sfirst « "0"b; 

49 end; 

50 put f ile(sysprint) 

51 list ("Enter data, or just a "";"« char: "-) ; 

52 get file(sysin) data (Fdeg, count); 
53 
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54 


/* Coitvpute and output each Fibonacci series. 


*/ 


SB- 


/* Then get next set of input values. 


*/ 




do while (Fdeg < 1 ) ; 






put f ile( syspr int) skip(2) data (count); 




• •;■ , 


put file( syspr int) skip; 




'St)? ■ • 


do i = 2 to Fdeg; 






call gen^fib (i, count); 






siiu ; 




63 


put f ile(syspr int) 






list ("New data, or just a char: 


") ? 




^tsu X ji c V a y s X 11 ; ud ua \cvac^ / wuuxiu^ f 




66 . 

67 - 


end ; 




68 






,6^ ■ '■: 


/* Close files and return. 


*/ 


70 

71 ^ 


close file(sysin) , f ile(sysprint) ;. 




72' 


return; 




73 
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74 gen fib: proc (grouping, count); 

75 

76 del (grouping, count) fixed bin, 

77 /* Fibonacci series to be computed, and number */ 

78 /* of items to be computed in the series, */ 

79 N (grouping) fixed bin(71) , 

80 /* Array of values summed to form series elements*/ 

81 result (-grouping :count-l ) char{28) varying, 

82 /* Array of output values, including assumed */ 

83 /* values which begin the series. */ 

84 r^matrix (Nrows, Ncols) char(28) varying based (Pr__matrix) , 

85 " /* 2~dimensional overlay for the computed output */ 

86 /* values (excluding assumed values) . */ 

87 Pr matrix ptr; 
88 

89 del (Icol , Irow, Ncols, Nrows , 

90 Nused_^cols_in_last row) fixed bin, 

91 Sdoes"not_f it bit(T) , 

92 SPACES char (30) int static options (constant) init("") , 

93 cycle fixed bin, 

94 /* index of series element being computed. */ 

95 f ormatted_total pic '•z2z,zzz,zzz,zzz,zz2,2zz,zz9" , 

96 output^total char (100) varying, 

97 total fixed bin(71); 
98 

99 

100 _ /* Initialize the assumed values which begin */ 

101 /* the series. All are 0 but the last, which is 1*/ 

102 

103 N(*) = 0; 

104 N (grouping-l) - 1; 
105 

106 

107 /* Put the assumed values in the output array. */ 
108 

109 do cycle = -grouping to -2; 

110 result(cycle) = "0"; 

111 end; 

112 result(cycle) = "1"; 

"1 "> 

^ M ~J 

114 

115 /* Compute remaining values of series, and put in */ 

116 /* the output array. */ 

117 

118 do cycle 0 to count-1; 

119 total = sum(N) ; 

120 formatted_total = total; 

121 result ( cycle) = Itr im ( f orraatted^^total) ; 

122 N (mod (cycle, grouping)) = total; 

123 end; 



124 
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125 


/* 


The output will be printed with assumed values 


*/ 


126 


/* 


preceding computed values. The computed values*/ 


127 


/* 


will be printed in as many rows as possible to 


*/ 


128 


/* 


reduce the number of output lines. However, if*/ 


129 


/* 


the output fits in 2 or more rows, the number 




130 


/* 


of rows is chosen so that all columns but the 


*/ 


131 


/* 


final one are full (have Nrows values) . 


* / 


132 


/* 


Of course, in multi-column format, all data 


*/ 


133 


/* 


must fit the terminal linesize. 


* / 


134 






135 


Pr 


matrix = addr(result(0) ) ; 




136 


Sdoes not fit = "l"b; 




137 


do 


Ncols = 20 to 1 by -1 while (Sdoes_not_f it) ; 




1 Q 
X J O 




ua X — ~ > 

Nrows = divide ( count+Ncols-1 , Ncols, 17, 0); 




139 






140 




Nused cols in last row ~ mod ( count , Ncols) ; 




141 




if Nused cols in last__^row = 0 then 




142 




Nused^coTs Tn^la¥t_row = Ncols; 




143 




if Nused cols in l"ast__row >= Ncols then do; 




144 




do Icol = 1 to Nused cols in last row; 




145 




total = total + 




146 




length(r matrix(Icol, Nrows))- 


147 




end; 




148 




do Icol = Icol to Ncols; 




149 




total = total + 




150 




length ( r^matr ix (Icol , Nrows 


1-1 


151 




end ; 




152 




if total <= linesize then Sdoes__no t_f i t 




153 




end; . 




154 


end ; 




155 


Ncols = Ncols + 1; 




156 
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157 /* Output the values, starting with the assumed */ 

158 /* values, then the computed (output in columns) , */ 

159 /* Computed values are output in right- justified */ 

160 /* columns. Each row (line) is formatted and */ 

161 /* then output. */ 
162 

163 put f iie( syspr int) edit ("Fdeg grouping, 

164 ":") {a, f (3) , a) ; 

165 put f ile(syspr int) edit {"{assumed beginning of series)", 

166 {result ( cycle) do cycle--grouping to -1)) 

167 (skip, a, skip, (grouping) (a , x(l))); 

168 put file( syspr int) 

169 edit ("{remainder of series) ") (skip, a); 

170 put f ile(syspr int) skip; 

171 do Irow = 1 to Nrows; 

172 msg =. ""; 

173 do Icol = 1 to Ncols-1; 

174 msg - msg i 1 substr (SPACES , 1, 

175 length ( r^matr ix (Icol , Nrows) ) - 

176 length ( r^matr ix (Icol , Irow) ) ) ; 

177 msg - msg II r^matr ix (Icol , Irow); 

178 msg = msg 11" "; 

179 end; 

180 if Irow*Ncols + Icol <= count then do; 

181 msg - msg M substr (SPACES , 1, 

182 length{result(hbound(result,l) ) ) - 

183 length ( r_^matr ix (Icol , Irow))); 

184 msg = msg il r^matr ix (Icol , Irow) • 

185 end; 

186 write file ( syspr int) from(msg); I 

187 end; 

188 put skip(2) f ile(sysprint) ; 

189 end gen__fib; 

190 

191 end fib; 
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1 logical sfirst /.true./ 

2 save sfirst 
3 

4 c Output instructions to the user, but only the first 

5 c time ' fib* is invoked in each process. 

6 

7 if ( .not .sfirst) goto 10 

8 print, "Enter first degree and count" 

9 print, "For example. First degree = 2, count = 10" 

10 print, "To stop, enter First degree = 1" 

11 sfirst = .false. 
12 

13 c Prompt for First degree and count. 

14 10 print, "First degree, count?" 

15 read, ifdeg, icount 

16 

17 c Stop when First degree is 1. 

18 if (ifdeg - 1) 15,15,25 
19 

20 15 print, "Count =", icount 

21 

22 c Compute and output each Fibonacci series. 

23 c Then get next set of input values, 

24 

25 do 22 i = 2, ifdeg 

26 22 call gen^^fib (i, icount) 

27 goto 10 

28 

29 25 stop 

30 end 
31 

32 

33 

34 subroutine gen fib (igrouping, icount) 

35 

36 c This subroutine actually computes the Fibonacci series. 

37 c ' iresult' will be filled with the proper values, 

38 c while ' jresult' is a convenient equivalent view of 

39 c the solution which will be used for printing purposes. 

40 c The ' n' array holds the most recent terms to be added 

41 c together to obtain the next term in the series. 
42 

43 double precision n(10), total 

44 dimension iresult(30) 

45 dimension j resul t { 10 , 3 ) 

46 equivalence ( iresult(l ) ,j result (1 , 1) ) 

47 

48 c Tell him which degree of Fibonacci series this is 

49 

50 print 

51 print, "Degree =", igrouping 
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52 






print 


53 








54 


c 




Initialize the assumed values which begin the 


55 


c 




series. All are 0 but the last, which is 


56 


c 




1 - also put the assumed values into the 


57 


c 




output array 


58 








59 






do 10 i = 1 , igrouping-1 


60 






iresult(i) = 0 


61 




10 


n{i) = 0 


62 






iresult ( igrouping) - 1 


63 






n(igrouping) = 1 


64 








65 


c 




Compute remaining values of series, and put in 


66 


c 




the output array 


67 








68 






do 20 icycle - igrouping+1, icount 


69 






total - 0 


70 






do 15 i = 1, igrouping 


71 




15 


total = total + n(i) 


72 






iresult( icycle) = total 


73 




20 


n(mod ( icycle-1 , igrouping) ) = total 


74 








75 


c 




The output will be printed with assumed values 


76 


c 




preceding computed values. The computed values 


77 


c 




will be printed along with the assumed values 


78 


c 




in three columns. Hence, there will always be 


79 


c 




' irow' rows with three values, and the last ' 


80 


c 




row may have 1 2 or 3 values 


81 






82 


• 




icol = mod ( icount , 3 ) 


83 






irow = icount / 3 


84 








85 
86 




22 


do 22 j=l,irow 

print, (jresult( i,j) ,i=l,3) 


87 






if (icol) 30,30,25 


88 




25 


print, (jresult{ irow+1 , i) ,i=l,icol) 


89 




30 


return 


90 






end 
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The following dialogue shows the correct operation of the PL/I version 
of the fib program. The dialogue is slightly different for the 
FORTRAN and COBOL versions, but the concept is basically the same for 
all three programs. The programs shown above may have errors which 
prevent them from generating these results. Use probe to find the 
errors. Change the source to correct "the errors, recompile the 
program and continue testing it until it prints the results shown 
below. 



1 I . pll fib -table 

2 PL/I 

3 r 2247 5.091 51.312 227 

4 

5 ! fib 

6 Enter Fdeg and/or count, followed by a character. 

7 For example, 

8 Fdeg = 2, count=10; 

9 These are the default values. To stop, enter 
10 Fdeg = 1; 

11 

12 Enter data, or just a char: I Fdeg = 4, count=9; 

13 
14 

15 counts 9; 

16 Fdeg =2: 

17 (assumed beginning of series) 

18 0 1 

19 (remainder of series) 

20 1 2 3 5 8 13 21 34 55 
21 

22 

23 Fdeg = 3: 

24 (assumed beginning of series) 

25 0 0 1 

26 (remainder of series) 

27 1 2 4 7 13 24 44 81 149 
28 

29 

30 Fdeg 4: 

31 (assumed beginning of series) 

32 0 0 0 1 

33 (remainder of series) 

34 1 2 4 8 15 29 56 108 208 
35 

36 

37 New data, or just a char: ! Fdeg=l; 

38 r 2248 0.249 0.228 19 



Not To Be Reproduced 



W-9 



F21 



WORKSHOP TWO 



A trace Workshop 



1« Use 'trace' to monitor the value of the arguments on return from 
the system program ' expand_pathname_' (trace -ag 1 -out 
expand__pathname_) , Do you know what that program is used for? 
Issue the trace^command to list the status of the expand^pathname^ 
trace entry (trace -status expand_^pathname___) . Do you know what 
those counters mean? Now issue a print command and observe what 
happens. Issue the command 'print >ldd> include> its . incl .pll ' and 
see what happens. Now try the command ' ds baloney'. Finally, try 
the command ' pr Ofoo', What happens? What do you think the 
fourth argument of expand^pathname__ is used for?? 



2. Now print the status of the expand_pathname_ (trace -status 
expand_^pathname_) . Also, list the control template for trace 
(trace"* -tp) . ""Remove the trace entry for expand__pathname__ and 
reset the control template to its initial form (trace -remove 
expand pathname__ -ag 0). 

3. Execute the following recursive program (see > udd>F19>sl>R2 . pll 
and >udd>F19>sl>R2) : 



R2: proc? 

del (sysin, sysprint) file; 

del (n, i) fixed bin; 

del R2$Seq entry (fixed bin); 

open file (sysprint) stream output env (interactive); 
put file (sysprint) skip list ("Enter value..."); 
get list ( n) ; 
call R2$Seq (n) ; 
.return;. 

Seq: entry ( i) ; 

put file (sysprint) list (i); 
if i > 1 then do; 

call R2$Seq (i-l); 

put file (sysprint) list (i); 

end; 

end; 



Execute the program with a value of 5. You should get 5 4 3 2 1 2 
3 4 5. Type the command to trace this program, printing the 
argument values at input to every second call (trace -in -ag 2 
R2$Seq) . Now run R2 again using the value 5 and observe what 
happens. List the trace status of R2$Seq and then turn on the 
governing facility (trace -st R2$Seq -govern on R2$Seq) . The 
governing facility is used to help trap runaway recursive 
procedures. Run R2 once again, using the value 5. List the 
status of R2$Seq(trace -st R2$Seq) . Note the maximum recursion 
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level. Now lets see if we can blow it out. Run R2 again, this 
time with an input of 12. What happened? Since our procedure is 
not really a runaway program, type the 'start' command to 
continue. Did you realize that we were at command level? 
Why? (Hint: the govern facility stops on depth levels which are a 
multiple of 10 to give you a chance" to find out what's happening). 



4. Now, stop tracing R2$Seq, and reset the template. You may first 
want to issue the command 'trace -st * -tp' to see the current 
state of affairs. Next, copy the following three simple pll 
programs, which are found in the directory >udd>F19>sl: 



init: proc; 

del 1 S external static, 

2 sentinel fixed bin, 

2 array (5) float; 
del ioa__ entry options (variable); 
del addr builtin; 

sentinel = 0; 

call ioa_ ("sentinel located at "p", addr (sentinel)); 

end; 



load: proc; 

del sysprint file; 

del 1 S external static, 

2 sentinel fixed bin, 

2 array (5) float; 
del i fixed bin; 

open file (sysprint) stream output env (interactive); 
do i = 1 to 5; 

array ( i) - 3* (i-2); 

end; 

put file (sysprint) skip (3) list (array); 

end ; 
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print^stat: proc; 

del sysprint file; 

del 1 S external static, 

2 sentinel fixed bin, 

2 array (5) float? 

open file (sysprint) stream output env (interactive); 
put skip (2) list ("*sentinel location clobbered I i*") ; 
put skip (1) data (S); 

end; 



Compile each of these programs. Now run init. It should tell you 
that the external static member variable 'sentinel' is located at 
some segment number I of f set. We want to use the watch facility of 
trace to find out whether any program is clobbering that location. 
Hence, issue the command to have trace watch that location -{tvisrr:e 
swatch seg__no I of f set) . Next, let's monitor the 'load' program, 
and if anything goes wrong, let's cause the print_^stat program to 
be called as the 'stop_^proc' instead of the command processor. 
Issue the command to do this(trace -stop__proc print stat load). 
Now run the load program and see what happens. So Tar so goodl 
Now modify the load program so that it inadvertently changes the 
value of sentinel by changing the 'do' statement to ' do i = 0 to 
5'. Recompile and run the load program. What happens? The watch 
facility should have stopped your load program since the value of 
its watch location changed, and it should have called the 
appropriate ' stop^^proc' . Did it? The watch facility is very 
useful when trying to track down the one procedure in a group of 
procedures that is going a bit awry, or has modified some 
externally accessible error cell, etc. 
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On the Programming Environment: A Quiz 



1. Object segments are an essential part of the Multics programming 
environment. Name the 8 sections into which an object segment is 
divided^ Describe the contents of each section in general terms. 
Are all the sections always present in every object segment? If 
not, which are optional. 
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The system maintains information about the user ring programming 
environment in 2 important segments. Can you name these 2 
segments? Briefly describe what kinds of data the system keeps 
in each segment. What directory are the segments located in? 
How are these segments protected from accidental damage? 
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3. One of the most powerful features of the Multics programming 
environment is the Dynamic Linking mechanism. The programming 
environment uses this mechanism to find an object segment which 
is called by another program. 



Briefly name the important steps taken by the 
find an object segment. 



dynamic linker to 



At what point during the compilation or execution of the calling 
program does dynamic linking take place? 



How often do-is it take place? 



If one prograiTi calls an object segment and then a second program 
(a second object segment) calls that same target object segment, 
are the same steps followed in both cases to dynamically link to 
the called object segment? If not, how does dynamic linking 
differ during the second call? 
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A fatal process error occurs when the system decides ^-hat the 
programming environment can no longer operate correctly. When 
this occurs, the system takes control of the user's terminal, 
prints a brief error message, and creates a new user process. 

Under what circumstances might the system decide that the 
il>rog ramming environment can no longer operate? 



What 2 programming errors are the most common causes of fatal 
process errors? 



Briefly describe a procedure for finding the cause of a fatal 
process error. 
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5. In chapter four 11 different classes of data (storage classes) 
were discussed which can be used in PL/I , FORTRAN and/or ..COBQl 
programs. For each class of data, describe: 

o Where the data is stored. Give the logical name of a 
segment, table, or area; also give the pathname of the 
segment containing the data class. 

o The major characteristics of the storage class. (When the 
data is allocated, when freed, when initialized, can it be 
shared between programs, etc?) ■ ■ \ , _ 

For example, one class of storage is: 



based storage, in an area: stored in a program-supplied area, 
such as the system free area (segment system^f ree_n__ in th-e 
process dir) . Storage is known only to 1 program, is 
expl ici tly allocated and freed, is initialized by allocate 
or locate statements, and has a location maintained by a 
pointer or offset qualifier. 
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5. (More .spasie for the answer) 



{q 3} 

V : 

\ ^ ■ . \ 

\ _. / Happiness is Multing the day away \ 
— / 

\ / 
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